MCP Endpoint

The /mcp endpoint exposes x402 RPC Proxy functionality as a set of callable tools using the MCP (Model Context Protocol) over JSON-RPC 2.0. It supports two protocol-level methods: tools/list to discover available tools, and tools/call to invoke them.

This design makes the endpoint natively compatible with AI agents and MCP clients as well as standard HTTP clients.

Endpoint

POST /mcp
Content-Type: application/json

Optional headers:

Header	Description
`Authorization: Bearer <jwt>`	Required for authenticated tools
`X-PAYMENT: <base64>`	x402 payment payload for credit top-up during RPC execution

Protocol Methods

`tools/list` — Discover Available Tools

Returns all registered tools with their names, descriptions, and input schemas.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "health_check",
        "description": "Check if the x402 RPC proxy service is healthy",
        "inputSchema": { "type": "object", "properties": {} }
      },
      ...
    ]
  }
}

`tools/call` — Invoke a Tool

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool-name>",
    "arguments": { ... }
  }
}

Success response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "json",
        "data": { ... }
      }
    ]
  }
}

Error response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "error description"
  }
}

Available Tools

`health_check`

Check if the x402 RPC proxy service is healthy.

Auth required: No

Arguments: None

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "health_check",
    "arguments": {}
  }
}

Response data:

json

{ "status": "ok" }

`generate_auth_nonce`

Generate a one-time nonce for wallet authentication. The nonce must be included in the sign-in message before calling auth_login.

Auth required: No

Arguments: None

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_auth_nonce",
    "arguments": {}
  }
}

Response data:

json

{ "nonce": "f3a1b8c9d2e4" }

`auth_login`

Authenticate a wallet using a signed SIWE or SIWC message and receive a JWT token.

Auth required: No

Arguments:

Field	Type	Required	Description
`message`	string	Yes	The full sign-in message that was signed
`auth_method`	string	Yes	`"siwe"` (Ethereum) or `"siwc"` (Cosmos)
`signature`	string	Yes	Wallet signature over the message
`address`	string	Yes	Wallet address
`pubkey`	string	`siwc` only	Public key (required for Cosmos ADR-036 verification)
`x402_ecosystem`	string	Yes	Ecosystem for payment routing (e.g. `"cosmos"`, `"evm"`)
`x402_chain_id`	string	Yes	Chain ID used for x402 payment settlement
`pricing_plan_id`	integer	Yes	Pricing plan the session is bound to

Example (SIWE):

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "auth_login",
    "arguments": {
      "message": "x402 Gateway wants you to sign in.\n\nAddress: 0xAbc...\nNonce: f3a1b8c9d2e4\nIssued At: 2024-06-01T12:00:00Z",
      "auth_method": "siwe",
      "signature": "0x4a3b...",
      "address": "0xAbc...",
      "x402_ecosystem": "evm",
      "x402_chain_id": "84532",
      "pricing_plan_id": 1
    }
  }
}

Example (SIWC):

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "auth_login",
    "arguments": {
      "message": "x402 Gateway wants you to sign in...",
      "auth_method": "siwc",
      "signature": "base64sig...",
      "address": "cosmos1abc...",
      "pubkey": "base64pubkey...",
      "x402_ecosystem": "cosmos",
      "x402_chain_id": "osmosis-1",
      "pricing_plan_id": 2
    }
  }
}

Response data:

json

{ "token": "eyJhbGciOiJIUzI1NiJ9..." }

INFO

The JWT encodes the wallet address, auth method, chain ID, x402 ecosystem, and pricing plan. All subsequent authenticated tool calls use this token.

`check_credit_balance`

Get remaining RPC credits for a wallet across all pricing plans.

Auth required: Yes
Wallet must match the authenticated session

Arguments:

Field	Type	Required	Description
`wallet`	string	Yes	Wallet address (must match JWT)

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_credit_balance",
    "arguments": {
      "wallet": "0xAbc..."
    }
  }
}

Response data:

json

{
  "wallet": "0xAbc...",
  "credits": [
    {
      "pricing_plan_id": 1,
      "remaining_credits": 9750
    }
  ]
}

`execute_rpc`

Execute a blockchain RPC call with x402 payment enforcement. Credits are atomically deducted before the request is forwarded to a provider.

If the credit balance is zero, the gateway returns a 402 error with payment requirements. The client can resolve the payment on-chain, attach the X-PAYMENT header, and retry — credits are then issued and the request proceeds in the same call.

Auth required: Yes

Arguments:

Field	Type	Required	Description
`ecosystem`	string	Yes	Blockchain ecosystem (e.g. `"evm"`, `"cosmos"`)
`chain_id`	string	Yes	Target chain ID (e.g. `"1"`, `"osmosis-1"`)
`resource`	string	Yes	URL path appended to the provider base URL (e.g. `"/"`, `"/cosmos/bank/v1beta1/balances/..."`)
`method`	string	Yes	HTTP method to use (`"POST"`, `"GET"`)
`transport`	string	Yes	Transport type (e.g. `"jsonrpc"`, `"rest"`)
`payload`	string	Yes	Request body as a JSON string

Required header for x402 payment:

http

X-PAYMENT: <base64-encoded JSON payment payload>

Example — EVM JSON-RPC call:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_rpc",
    "arguments": {
      "ecosystem": "evm",
      "chain_id": "1",
      "resource": "/",
      "method": "POST",
      "transport": "jsonrpc",
      "payload": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_blockNumber\",\"params\":[]}"
    }
  }
}

Example — Cosmos REST call:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_rpc",
    "arguments": {
      "ecosystem": "cosmos",
      "chain_id": "osmosis-1",
      "resource": "/cosmos/bank/v1beta1/balances/osmo1abc...",
      "method": "GET",
      "transport": "rest",
      "payload": ""
    }
  }
}

Response data (success):

json

{
  "status": 200,
  "content_type": "application/json",
  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":\"0x12a05f2\"}",
  "remaining_credits": 9749
}

Response on insufficient credits (402):

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 402,
    "message": "payment_required_x402",
    "data": {
      "scheme": "exact",
      "network": "84532",
      "asset": "0xUSDC...",
      "maxAmountRequired": "10000000",
      "payTo": "0xTreasury...",
      "maxTimeoutSeconds": 300,
      "description": "pay above amount to get 10000 credits"
    }
  }
}

`get_providers`

List all registered RPC and REST providers across all supported chains.

Auth required: Yes

Arguments: None

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_providers",
    "arguments": {}
  }
}

Response data:

json

{
  "providers": [
    {
      "id": 1,
      "name": "Ethereum Mainnet",
      "ecosystem": "evm",
      "chain_id": "1",
      "transport": "jsonrpc",
      "url": "https://..."
    }
  ]
}

`get_supported_payment_networks`

Returns the payment kinds and networks supported by the x402 facilitator.

Auth required: No

Arguments: None

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_supported_payment_networks",
    "arguments": {}
  }
}

Response data:

json

{
  "kinds": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "asset": "0xUSDC..."
    }
  ]
}

`get_wallet_history`

Get paginated RPC usage history for a wallet.

Auth required: Yes
Wallet must match the authenticated session

Arguments:

Field	Type	Required	Default	Description
`wallet`	string	Yes	—	Wallet address (must match JWT)
`limit`	integer	No	`20`	Number of records to return
`offset`	integer	No	`0`	Pagination offset

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_wallet_history",
    "arguments": {
      "wallet": "0xAbc...",
      "limit": 10,
      "offset": 0
    }
  }
}

`get_wallet_payments`

Get paginated payment transaction history for a wallet.

Auth required: Yes
Wallet must match the authenticated session

Arguments:

Field	Type	Required	Default	Description
`wallet`	string	Yes	—	Wallet address (must match JWT)
`limit`	integer	No	`30`	Number of records to return
`offset`	integer	No	`0`	Pagination offset

Example:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_wallet_payments",
    "arguments": {
      "wallet": "0xAbc...",
      "limit": 30,
      "offset": 0
    }
  }
}

Tool Summary

Tool	Auth	Description
`health_check`	No	Service health check
`generate_auth_nonce`	No	Generate nonce for wallet sign-in
`auth_login`	No	Authenticate wallet and receive JWT
`get_supported_payment_networks`	No	List x402 payment kinds and networks
`check_credit_balance`	Yes	Get remaining credits for a wallet
`get_providers`	Yes	List registered RPC/REST providers
`execute_rpc`	Yes	Execute a blockchain RPC call with credit enforcement
`get_wallet_history`	Yes	Paginated RPC usage history
`get_wallet_payments`	Yes	Paginated payment transaction history

Error Codes

Code	Description
`-32700`	Parse error — invalid JSON
`-32601`	Method not found — only `tools/list` and `tools/call` are valid
`-32001`	Tool error — authentication failure, validation error, or upstream RPC error
`-32000`	Tool not found — unknown tool name in `tools/call`
`402`	Payment required — insufficient credits; `error.data` contains x402 payment requirements

x402 Payment Flow in `execute_rpc`

When a 402 error is returned by execute_rpc, the client should:

Read error.data for payment requirements (asset, maxAmountRequired, payTo, network)
Make the on-chain transfer to payTo
Construct the x402 payment payload (verify + settle structure)
Base64-encode it and attach as the X-PAYMENT header
Retry the same execute_rpc call

The gateway will verify the payment on-chain, settle it, issue credits, and execute the RPC — all in a single request.

MCP Endpoint ​

Endpoint ​

Protocol Methods ​

tools/list — Discover Available Tools ​

tools/call — Invoke a Tool ​

Available Tools ​

health_check ​

generate_auth_nonce ​

auth_login ​

check_credit_balance ​

execute_rpc ​

get_providers ​

get_supported_payment_networks ​

get_wallet_history ​

get_wallet_payments ​

Tool Summary ​

Error Codes ​

x402 Payment Flow in execute_rpc ​

MCP Endpoint

Endpoint

Protocol Methods

`tools/list` — Discover Available Tools

`tools/call` — Invoke a Tool

Available Tools

`health_check`

`generate_auth_nonce`

`auth_login`

`check_credit_balance`

`execute_rpc`

`get_providers`

`get_supported_payment_networks`

`get_wallet_history`

`get_wallet_payments`

Tool Summary

Error Codes

x402 Payment Flow in `execute_rpc`