REST API

The x402 RPC Proxy exposes a set of REST endpoints for wallet authentication, pricing discovery, credit management, RPC execution, and usage history.

All endpoints follow standard HTTP conventions. Authenticated endpoints require a JWT obtained via the wallet login flow.

Base URL

https://<your-gateway-host>

Authentication

Authenticated endpoints require a wallet-issued JWT in the Authorization header:

http

Authorization: Bearer <jwt>

The JWT is obtained by completing the SIWE or SIWC sign-in flow. It encodes the wallet address, auth method, chain ID, x402 ecosystem, and pricing plan.

Endpoints

Health

`GET /health`

Check if the gateway is running.

Auth: Not required

Response:

json

{ "status": "ok" }

Authentication

`GET /auth/nonce`

Generate a one-time nonce to include in the wallet sign-in message. Nonces expire after 5 minutes.

Auth: Not required

Response:

json

{ "nonce": "f3a1b8c9d2e4" }

`POST /auth/login`

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

Auth: Not required

Request body:

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	Base64 public key (required for Cosmos ADR-036 verification)
`x402_chain_id`	string	Yes	Chain ID used for x402 payment settlement (e.g. `"84532"`, `"osmosis-1"`)
`x402_ecosystem`	string	Yes	Ecosystem for payment routing (`"evm"` or `"cosmos"`)
`pricing_plan_id`	integer	Yes	ID of the pricing plan the session is bound to

Example (SIWE):

http

POST /auth/login
Content-Type: application/json

{
  "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_chain_id": "84532",
  "x402_ecosystem": "evm",
  "pricing_plan_id": 1
}

Example (SIWC):

http

POST /auth/login
Content-Type: application/json

{
  "message": "x402 Gateway wants you to sign in...",
  "auth_method": "siwc",
  "signature": "base64sig...",
  "address": "cosmos1abc...",
  "pubkey": "base64pubkey...",
  "x402_chain_id": "osmosis-1",
  "x402_ecosystem": "cosmos",
  "pricing_plan_id": 2
}

Response:

json

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

INFO

The JWT embeds the wallet address, auth method, chain ID, x402 ecosystem, and pricing plan ID. It is used as the session token for all authenticated endpoints.

Pricing Plans

`GET /pricing`

List all active pricing plans available for purchase.

Auth: Not required

Response:

json

[
  {
    "id": 1,
    "plan_name": "Starter",
    "chain_id": "84532",
    "network": "base-sepolia",
    "ecosystem": "evm",
    "asset_address": "0xUSDC...",
    "amount": "10000000",
    "decimals": 6,
    "display_denom": "USDC",
    "credits": 10000,
    "pay_to": "0xTreasury..."
  }
]

`GET /pricing/:id`

Get details of a specific pricing plan by ID.

Auth: Not required

Path parameters:

Param	Description
`id`	Pricing plan ID (integer)

Response:

json

{
  "data": {
    "id": 1,
    "plan_name": "Starter",
    "chain_id": "84532",
    "network": "base-sepolia",
    "ecosystem": "evm",
    "asset_address": "0xUSDC...",
    "amount": "10000000",
    "decimals": 6,
    "display_denom": "USDC",
    "credits": 10000,
    "pay_to": "0xTreasury..."
  }
}

Providers

`GET /providers`

List all registered RPC and REST providers.

Auth: Not required

Response:

json

{
  "data": [
    {
      "id": 1,
      "provider_id": "my-provider",
      "category": "evm",
      "chain_id": "1",
      "rpc": ["https://rpc.example.com"],
      "rest": [],
      "description": "Ethereum Mainnet"
    }
  ]
}

`GET /providers/:id`

Get a specific provider by provider ID, filtered by category and chain.

Auth: Not required

Path parameters:

Param	Description
`id`	Provider ID string

Query parameters:

Param	Required	Description
`category`	Yes	Ecosystem category (e.g. `"evm"`, `"cosmos"`)
`chain_id`	Yes	Chain ID (e.g. `"1"`, `"osmosis-1"`)

Example:

http

GET /providers/my-provider?category=evm&chain_id=1

Response:

json

{
  "data": {
    "provider_id": "my-provider",
    "category": "evm",
    "chain_id": "1",
    "rpc": ["https://rpc.example.com"],
    "rest": []
  }
}

x402 Payment Networks

`GET /x402/supported`

Returns the payment schemes and networks supported by the x402 facilitator. Use this to discover which assets and chains are valid for on-chain payments.

Auth: Not required

Response:

json

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

RPC Execution

`POST /rpc`

Execute a blockchain RPC or REST call through the gateway with x402 credit enforcement.

Credits are atomically deducted before forwarding the request. If the balance is zero, a 402 Payment Required response is returned with payment details. Attach the X-PAYMENT header to resolve the payment inline and retry.

Auth: Required (JWT via Authorization: Bearer <token>)

Required headers:

Header	Description
`Authorization`	`Bearer <jwt>` from wallet login
`Content-Type`	`application/json`
`X-PAYMENT`	(optional) x402 payment payload when resolving a 402

x402 payment header format:

For SIWE sessions, X-PAYMENT is the raw EIP-3009 / ERC-20 signed payment payload string.

For SIWC sessions, X-PAYMENT is a base64-encoded JSON object containing paymentPayload and paymentRequirements.

Request body:

Field	Type	Required	Description
`ecosystem`	string	Yes	Target blockchain ecosystem (`"evm"`, `"cosmos"`)
`chain_id`	string	Yes	Target chain ID (e.g. `"1"`, `"osmosis-1"`)
`resource`	string	Yes	URL path appended to provider base URL (e.g. `"/"`, `"/cosmos/bank/v1beta1/balances/..."`)
`method`	string	Yes	HTTP method to forward (`"POST"`, `"GET"`)
`transport`	string	Yes	Transport type: `"rpc"` or `"rest"`
`payload`	object	Yes	Request body to forward to the provider

Example — EVM JSON-RPC:

http

POST /rpc
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "ecosystem": "evm",
  "chain_id": "1",
  "resource": "/",
  "method": "POST",
  "transport": "rpc",
  "payload": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  }
}

Example — Cosmos REST:

http

POST /rpc
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "ecosystem": "cosmos",
  "chain_id": "osmosis-1",
  "resource": "/cosmos/bank/v1beta1/balances/osmo1abc...",
  "method": "GET",
  "transport": "rest",
  "payload": {}
}

Success: Returns the upstream provider response transparently (status code, content-type, and body are proxied as-is).

402 Payment Required (insufficient credits):

http

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "status": 402,
  "message": "Payment Required (x402)",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "84532",
    "asset": "0xUSDC...",
    "maxAmountRequired": "10000000",
    "mimeType": "application/json",
    "payTo": "0xTreasury...",
    "maxTimeoutSeconds": 300,
    "description": "pay above amount to get 10000 credits"
  }
}

Once the on-chain payment is made, attach the payment proof as X-PAYMENT and resend the same request. Credits will be issued and the RPC call will proceed.

Credits

`GET /credits/:wallet`

Get credit balances for a wallet address across all pricing plans.

Auth: Not required

Path parameters:

Param	Description
`wallet`	Wallet address

Response:

json

[
  {
    "pricing_plan_id": 1,
    "remaining_credits": 9750
  }
]

Usage History

`GET /history/:wallet`

Get paginated RPC usage history for a wallet.

Auth: Not required

Path parameters:

Param	Description
`wallet`	Wallet address

Query parameters:

Param	Default	Description
`limit`	`20`	Number of records to return
`offset`	`0`	Pagination offset
`plan_id`	—	(optional) Filter by pricing plan ID

Example:

http

GET /history/0xAbc...?limit=10&offset=0&plan_id=1

Payments

`GET /payments/:wallet`

Get paginated payment transaction history for a wallet.

Auth: Not required

Path parameters:

Param	Description
`wallet`	Wallet address

Query parameters:

Param	Default	Description
`limit`	`30`	Number of records to return
`offset`	`0`	Pagination offset

Example:

http

GET /payments/0xAbc...?limit=30&offset=0

Error Responses

Status	Description
`400`	Bad request — invalid or missing fields
`401`	Unauthorized — missing or invalid JWT
`402`	Payment required — no credits; see `paymentRequirements`
`404`	Not found — unknown provider, chain, or plan
`500`	Internal error — upstream or gateway failure

x402 Payment Flow for `/rpc`

When /rpc returns 402, the client should:

Read paymentRequirements from the response body
Make the on-chain transfer to payTo using the specified asset on the specified network
Construct the payment proof:
- SIWE: the signed EIP-3009 authorization string
- SIWC: base64-encoded JSON with paymentPayload and paymentRequirements
Set this as the X-PAYMENT request header
Resend the original /rpc request

The gateway verifies and settles the payment on-chain, issues credits, and executes the RPC — all in the same request.

REST API ​

Base URL ​

Authentication ​

Endpoints ​

Health ​

GET /health ​

Authentication ​

GET /auth/nonce ​

POST /auth/login ​

Pricing Plans ​

GET /pricing ​

GET /pricing/:id ​

Providers ​

GET /providers ​

GET /providers/:id ​

x402 Payment Networks ​

GET /x402/supported ​

RPC Execution ​

POST /rpc ​

Credits ​

GET /credits/:wallet ​

Usage History ​

GET /history/:wallet ​

Payments ​

GET /payments/:wallet ​

Error Responses ​

x402 Payment Flow for /rpc ​

REST API

Base URL

Authentication

Endpoints

Health

`GET /health`

Authentication

`GET /auth/nonce`

`POST /auth/login`

Pricing Plans

`GET /pricing`

`GET /pricing/:id`

Providers

`GET /providers`

`GET /providers/:id`

x402 Payment Networks

`GET /x402/supported`

RPC Execution

`POST /rpc`

Credits

`GET /credits/:wallet`

Usage History

`GET /history/:wallet`

Payments

`GET /payments/:wallet`

Error Responses

x402 Payment Flow for `/rpc`