ReqCast Developer Reference

ReqCast is payment infrastructure for the AI agent economy. It sits between AI agents and the API tools they need to call. Developers register their tool once and get paid in USDC every time an agent calls it. No payment code required on your side.

Base URL: https://api.reqcast.com

Network: Base Mainnet (eip155:8453) · Currency: USDC

Quickstart

Get your tool live and accepting payments from AI agents in two steps.

Step 1 — Register your tool

Send one POST request with your wallet address, tool name, price per call, and the callback URL ReqCast will hit after payment is verified.

curl -X POST https://api.reqcast.com/register \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address":  "0xYOUR_WALLET",
    "tool_name":       "your-tool-name",
    "price_per_call":  "0.10",
    "callback_url":    "https://your-server.com/your-tool",
    "timeout_seconds": 10
  }'

ReqCast responds with your dedicated payment endpoint:

{
  "status":          "registered",
  "tool_name":        "your-tool-name",
  "price_per_call":   "0.10",
  "pay_endpoint":     "/pay/your-tool-name",
  "timeout_seconds":  10,
  "warning":          null
}

Step 2 — Build your callback

ReqCast calls your callback_url after payment is verified. Your endpoint receives the buyer payload and returns any JSON result.

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/your-tool")
async def handle(request: Request):
    body = await request.json()

    # X-ReqCast-Verified: true confirms payment cleared
    user_input = body["input"]

    result = your_tool_logic(user_input)

    return {"result": result}

That is the full integration. ReqCast handles payment verification, the USDC split, and receipt generation. You just return your tool output.

x402 client setup

To call a tool registered on ReqCast, the buyer needs an x402-compatible client. This is typically an AI agent or an automated script with a USDC wallet on Base.

import asyncio
from eth_account import Account
from x402 import x402Client
from x402.mechanisms.evm.exact import register_exact_evm_client
from x402.http.clients.httpx import x402HttpxClient

async def call_tool():
    account = Account.from_key("YOUR_PRIVATE_KEY")

    client = x402Client()
    register_exact_evm_client(
        client,
        account,
        networks=['eip155:8453']
    )

    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://api.reqcast.com/pay/your-tool-name",
            json={"buyer_payload": {"query": "your input"}}
        )
        print(response.json())

asyncio.run(call_tool())

GET /health

Returns server status, uptime, transaction statistics, and a link to the interactive docs. Use this to verify the API is alive before integrating.

{
  "status":           "ok",
  "version":          "1.0.0",
  "environment":      "mainnet",
  "network":          "base",
  "uptime":           "12h 33m",
  "registered_tools": 3,
  "transactions": {
    "total":        47,
    "completed":    46,
    "failed":       1,
    "success_rate": "97.9%"
  },
  "last_transaction": "2026-03-18T14:32:00Z",
  "docs":             "https://api.reqcast.com/docs"
}

GET /tools

Returns all registered tools with their price per call and pay endpoint. Use this to discover what tools are available on ReqCast.

{
  "tools": [
    {
      "tool_name":      "crypto-price-feed",
      "price_per_call": "0.01",
      "pay_endpoint":   "https://api.reqcast.com/pay/crypto-price-feed",
      "registered_at":  "2026-03-18T22:40:24Z"
    }
  ],
  "total": 1
}

POST /register

Register your tool with ReqCast. This creates a dedicated payment endpoint at /pay/{tool_name} with its own x402 price. ReqCast pings your callback URL at registration time and rejects unreachable URLs.

{
  "wallet_address":  "0xYOUR_WALLET",
  "tool_name":       "your-tool-name",
  "price_per_call":  "0.10",
  "callback_url":    "https://your-server.com/your-tool",
  "timeout_seconds": 10
}

{
  "wallet_address":        "0xYOUR_WALLET",
  "tool_name":             "your-tool-name",
  "price_per_call":        "0.10",
  "callback_url":          "https://your-server.com/your-tool",
  "timeout_seconds":       10,
  "callback_auth_header":  "X-API-Key",
  "callback_auth_value":   "your-secret-key",
  "callback_payload_mode": "passthrough"
}

{
  "status":          "registered",
  "tool_name":        "your-tool-name",
  "price_per_call":   "0.10",
  "pay_endpoint":     "/pay/your-tool-name",
  "timeout_seconds":  10,
  "warning":          null
}

{
  "detail": "Tool 'your-tool-name' is already registered."
}

{
  "detail": "Callback URL 'https://...' is not reachable."
}

POST /pay/{tool_name}

The endpoint AI agents call to use a registered tool. Each tool has its own dedicated route with its own x402 price. Payment is verified on-chain before your tool runs.

{
  "buyer_payload": {
    "query": "your input here"
  }
}

{
  "transaction_id": "uuid",
  "result": { ...tool output... },
  "receipt": {
    "transaction_id":   "uuid",
    "tool_name":        "your-tool-name",
    "status":           "completed",
    "timestamp":        "2026-03-18T14:32:00Z",
    "price_usdc":       0.10,
    "developer_cut":    0.095,
    "reqcast_cut":      0.005,
    "developer_wallet": "0xYOUR_WALLET",
    "payout_tx_hash":   "0x..."
  }
}

{
  "detail": "Tool 'your-tool-name' timed out. Payment not charged."
}

GET /receipt/{transaction_id}

Returns the full tamper-evident receipt for a completed transaction. The payout_tx_hash is verifiable on BaseScan as proof of on-chain payout.

{
  "transaction_id":   "uuid",
  "tool_name":        "your-tool-name",
  "status":           "completed",
  "timestamp":        "2026-03-18T14:32:00Z",
  "price_usdc":       0.10,
  "developer_cut":    0.095,
  "reqcast_cut":      0.005,
  "developer_wallet": "0xYOUR_WALLET",
  "payout_tx_hash":   "0x...",
  "tool_result":      { ...tool output... }
}

Verify any payout_tx_hash at: basescan.org

GET /status/{transaction_id}

Returns the current state of a transaction. Useful for AI agents to check if they should retry or move on.

{
  "transaction_id": "uuid",
  "status":         "completed",
  "timestamp":      "2026-03-18T14:32:00Z"
}

Failures and refunds

Understanding how ReqCast handles failures is important before you bring real users to your tool.

How payment timing works

The x402 protocol verifies and moves USDC on-chain before ReqCast calls your tool. This means payment is captured the moment the agent sends a valid signed transaction, not after your tool responds.

When the buyer is not charged

If ReqCast cannot reach your callback URL at all, or if your tool fails to respond before the request even reaches your server, the buyer is not charged. ReqCast returns a 502 and no USDC moves.

When the buyer is charged and the tool fails

If your callback URL is reached but your tool returns an error or times out after payment has already been verified, ReqCast automatically initiates a refund to the buyer wallet. The refund engine retries up to 3 times with a 2-second delay between attempts.

What to do if a dispute arises

Contact us at [email protected] with the transaction ID and payout tx hash. Every transaction has a full on-chain audit trail. Disputes are handled manually on a case by case basis.

Best practices for tool developers

• Make your callback URL highly reliable. Use a server with good uptime.
• Set a realistic timeout. If your tool takes 20 seconds, register with timeout_seconds: 25.
• Return a meaningful error response if something goes wrong so the buyer understands what happened.
• Test your callback URL thoroughly before going live. Use Base Sepolia testnet for initial testing.