x402 Nano Payments for RPC Requests

x402 is a pay-per-request protocol for APIs. When enabled for an action, Nano.to returns an HTTP 402 Payment Required challenge instead of requiring an API key or prepaid balance. A compatible client pays the exact Nano amount in the challenge, signs the payment, and retries the same request with a PAYMENT-SIGNATURE header.

Availability

x402 is configured by the RPC service and may not be enabled for every deployment or action. The current default action is work_generate; the enabled action list is controlled by the service configuration. Treat the integration as experimental and test with small amounts.

x402 is intentionally anonymous-only:

• Requests with any extracted RPC credential, including an invalid one, skip the x402 branch and continue through normal account authentication. Do not send Authorization, key, or another RPC credential when you want an x402 challenge.
• Requests without a credential can receive an x402 challenge when their action is configured.
• x402 does not create an account, issue an API key, activate an agent key, add prepaid credits, or replace the account-bound buy_rpc funding flow.

Step 1: Request the resource

Send the request normally, without PAYMENT-SIGNATURE:

curl -i -X POST https://rpc.nano.to \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "work_generate",
    "hash": "FRONTIER_HASH"
  }'

When x402 is enabled for the action, the response is 402 and includes a base64-encoded PAYMENT-REQUIRED header. The JSON body also indicates that payment is required.

Step 2: Read the payment requirements

The decoded requirements currently have this shape:

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "nano:mainnet",
  "amount": "RAW_AMOUNT",
  "asset": "XNO",
  "payTo": "nano_1configured_destination...",
  "maxTimeoutSeconds": 60,
  "resource": {
    "url": "https://rpc.nano.to/",
    "description": "Paid Nano RPC action: work_generate",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "nano:mainnet",
      "amount": "RAW_AMOUNT",
      "asset": "XNO",
      "payTo": "nano_1configured_destination...",
      "maxTimeoutSeconds": 60
    }
  ]
}

The amount is in Nano raw units. Use the exact amount, payTo, network, and resource from the current challenge. Never hardcode the price or destination.

maxTimeoutSeconds is used by the service while it waits for confirmation after settlement. It is not currently a signed payment expiry or a guarantee that an old challenge will be rejected. Request a fresh challenge and create a fresh payment whenever the request changes or a previous attempt is uncertain.

To inspect a challenge in Node.js:

const requirements = JSON.parse(
  Buffer.from(paymentRequiredHeader, 'base64').toString('utf8')
)
console.log(requirements.accepts)

Step 3: Create an exact Nano payment

Use a compatible x402 Nano client to construct and sign an exact payment. The official Nano scheme package provides Client, Resource Server, and Facilitator implementations and runnable examples:

npm install @x402/core @x402nano/exact @x402nano/helper

The client must create a Nano send state block for the exact raw amount and destination in PAYMENT-REQUIRED, then serialize the x402 payment payload according to the Nano exact scheme. Do not manually copy an old payment payload or reuse a payment intended for another resource.

See the @x402nano/exact examples for the client-side signing flow. Test with small amounts only while integrating.

Step 4: Retry with PAYMENT-SIGNATURE

Send the original RPC body again and include the signed, base64-encoded x402 payment payload:

curl -i -X POST https://rpc.nano.to \
  -H 'Content-Type: application/json' \
  -H 'PAYMENT-SIGNATURE: BASE64_SIGNED_PAYMENT_PAYLOAD' \
  -d '{
    "action": "work_generate",
    "hash": "FRONTIER_HASH"
  }'

The payment signature is a credential for this request. Keep it out of logs, prompts, browser analytics, and error reports.

Server verification and settlement

Nano.to validates the payment requirements, asks the facilitator to verify and settle the payment, and then checks the confirmed Nano send against the required amount and destination. The paid RPC action runs only after settlement and confirmation match the challenge.

Current implementation limitation

Settlement happens before the downstream RPC action runs. If payment settles but the action later fails because the hash, request body, upstream node, or service state is invalid, Nano.to does not automatically refund the payment. The same signed payment should not be blindly reused. Use x402 only for configured actions whose failure and retry behavior you can reconcile, and test with small amounts.

The current local validation and facilitator flow checks payment scheme, network, amount, and destination. It does not cryptographically bind the payment to the RPC action, resource URL, or complete request body. Your client must verify that the challenge resource and intended action match before signing, and you should not use a payment payload received for one action to authorize another.

Successful responses include a PAYMENT-RESPONSE header containing the facilitator settlement result. Store your own request and block identifiers if you need audit or reconciliation data.

Errors

• 402: missing, malformed, underpaid, wrong-destination, wrong-network, or otherwise invalid payment.
• 503: the Nano payment facilitator or payment-check service is temporarily unavailable. Retry later, but do not create a second payment without checking the first payment state.
• 429: x402 is not account authentication or an entitlement. Once an x402 payment is accepted, account free/credit checks are not what authorizes the request; action-specific service or abuse failures can still occur.
• 400 or action errors: the original RPC request is invalid; fix the request rather than paying repeatedly.

If a payment was broadcast but the request returned an error, retain the signed payload and transaction/block hash, then verify settlement before paying again. A pending payment is not automatically a failed payment, and a settled payment is not automatically a successful RPC result.

x402 is not account funding

x402 pays for one configured RPC request. It does not:

• Add credits to an account.
• Activate a funding_only AGENT-KEY-....
• Create a subscription.
• Replace buy_rpc.
• Provide merchant Checkout or webhook fulfillment.

Use the AI Agent guide for account-bound agent funding and the Checkout API for merchant payments.

Security checklist

• Parse every new PAYMENT-REQUIRED challenge.
• Match the action and resource to your intended request.
• Pay the exact raw amount and destination.
• Use a fresh payment payload for the current challenge; do not assume the service enforces signed challenge expiry or request-body binding.
• Keep signing keys and payment signatures server-side.
• Verify the original request is safe to repeat before retrying.
• Reconcile the confirmed block before declaring the paid action successful.

Related references: RPC API, Proof of Work, Rate Limits, AI Agent Integration, and x402 Nano exact.