Tool Creation Guide

Learn how to build X402-compatible tools that work seamlessly with Miraipay's AI agent and earn MNEE tokens from every interaction.

Quick Start

Build Your API

Create a REST API endpoint that performs a useful function. Can be anything from data retrieval to complex computations.

Add X402 Protocol

Implement the X402 payment protocol to accept MNEE micropayments. Return 402 status with payment headers.

Register & Earn

Submit your tool to Miraipay's registry. Once approved, earn MNEE tokens every time the AI agent uses your tool.

Understanding X402 Protocol

X402 is an HTTP extension that enables seamless micropayments for API usage. It's built on HTTP 402 Payment Required status code with additional headers for payment details.

Step 1: Initial Request

Client calls your API without payment

Step 2: Payment Required Response

Your API returns 402 with payment details in headers

Step 3: Payment Processing

Client transfers MNEE tokens to your wallet address

Step 4: Retry with Proof

Client retries request with X-Payment-Proof header (transaction hash)

Step 5: Service Delivery

Your API validates payment and returns the response

Python (FastAPI) Example

from fastapi import APIRouter, HTTPException, Header, Response
from typing import Optional

router = APIRouter()

@router.post("/your-tool")
async def your_tool_endpoint(
    data: YourRequestModel,
    x_payment_proof: Optional[str] = Header(None),
    response: Response = None
):
    # Check for payment proof
    if not x_payment_proof:
        response.status_code = 402
        response.headers["X-Accept-Payment"] = "MNEE"
        response.headers["X-Payment-Address"] = "0xYourWalletAddress"
        response.headers["X-Payment-Amount"] = "1.5"  # Price in MNEE
        response.headers["X-Payment-Network"] = "ethereum"
        response.headers["X-Payment-Contract"] = "0x8ccedbAe4916b79da7F3F612EfB2EB93A2bFD6cF"
        
        raise HTTPException(
            status_code=402,
            detail={
                "error": "Payment Required",
                "message": "Please pay 1.5 MNEE to use this tool",
                "payment_address": "0xYourWalletAddress",
                "amount": "1.5",
                "currency": "MNEE"
            }
        )
    
    # Validate payment proof (transaction hash)
    if not x_payment_proof.startswith("0x") or len(x_payment_proof) != 66:
        raise HTTPException(status_code=400, detail="Invalid transaction hash")
    
    # Your tool logic here
    result = perform_your_service(data)
    
    return {"success": True, "data": result}

Tool Metadata Format

When registering your tool on Miraipay, provide this JSON metadata:

Tool Registration JSON

{
  "name": "Weather Forecast API",
  "description": "Get 7-day weather forecast for any city worldwide with detailed hourly breakdowns",
  "category": "Data & Information",
  "endpoint": "https://your-api.com/api/weather/forecast",
  "method": "POST",
  "price": "0.5",
  "parameters": [
    {
      "name": "city",
      "type": "string",
      "description": "City name (e.g., 'Toronto', 'New York')",
      "required": true
    },
    {
      "name": "days",
      "type": "integer",
      "description": "Number of forecast days (1-7)",
      "required": false,
      "default": 7
    },
    {
      "name": "units",
      "type": "string",
      "description": "Temperature units: 'celsius' or 'fahrenheit'",
      "required": false,
      "default": "celsius"
    }
  ],
  "return_type": {
    "type": "object",
    "properties": {
      "city": "string",
      "forecast": "array of daily forecasts",
      "temperature_unit": "string"
    }
  },
  "example_request": {
    "city": "Toronto",
    "days": 5,
    "units": "celsius"
  },
  "example_response": {
    "city": "Toronto",
    "forecast": [
      {
        "date": "2025-01-15",
        "high": 5,
        "low": -2,
        "condition": "Partly Cloudy"
      }
    ]
  }
}

name:Short, descriptive name (50 chars max)

description:Detailed explanation of what your tool does (500 chars max)

category:Data & Information, Communication, Finance, Entertainment, Productivity, Development

price:Cost in MNEE tokens per API call

Testing Your Tool

Manual Testing with cURL

Step 1: Test without payment

curl -X POST https://your-api.com/api/your-tool \
  -H "Content-Type: application/json" \
  -d '{"param1": "value1"}' \
  -v

Should return 402 with payment headers

Step 2: Test with mock payment proof

curl -X POST https://your-api.com/api/your-tool \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: 0xabc123def456..." \
  -d '{"param1": "value1"}'

Should return your tool's response