x402 nanopayments - Edge RPC

Copy prompt

Open in Claude

Open in ChatGPT

Open in Perplexity

Edge RPC accepts payments over the x402 protocol, funded through Circle Gateway. Fund a USDC balance once with Circle and call any chain Edge serves, with no Goldsky account, no API key, and no invoice. Edge does not settle every call with Circle. Your first paid request tops up a small prepaid balance, and later calls are deducted from it. This keeps the price at $0.000005 per call at high request rates, where one settlement per call would not scale. x402 is designed for autonomous agents. SDK clients handle the full handshake transparently.

Pricing

$5 per million requests, all methods, all chains.

Each call costs 5 atomic USDC ($0.000005). A JSON-RPC batch is billed per call in the batch.
A top-up is at least 5000 atomic USDC ($0.005), which covers about 1,000 calls. If you sign for more than the minimum, the whole amount is credited.
Your balance is held by Goldsky and tied to your wallet address. It does not expire, and it covers every chain Edge serves, whichever chain you paid on.
Settlement is gasless on your side. Circle Gateway debits your deposit once per top-up, not once per call.

Endpoint

Edge RPC endpoints follow a single URL pattern, with the chain ID in the path:

https://edge.goldsky.com/standard/evm/{chainId}

To discover every chain Edge serves, hit edge.goldsky.com with no path. It returns a JSON list of every supported network, with CAIP id, alias, block time, and health status:

curl https://edge.goldsky.com | jq '.standard[] | {id, alias, state}'
# {"id": "evm:1",     "alias": "ethereum-mainnet", "state": "OK"}
# {"id": "evm:8453",  "alias": "base",             "state": "OK"}
# {"id": "evm:42161", "alias": "arbitrum",         "state": "OK"}
# ...

Supported chains for x402 payments

The chain you pay on is independent of the chain you query. The table below lists the 12 networks you can settle payments on. It mirrors the live list at https://gateway-api.circle.com/v1/x402/supported. You can pay with USDC on any one of them and then query any chain Edge serves, including chains that aren’t in this table and chains with no USDC of their own. For example: fund on Base, then read Robinhood Chain. One Gateway balance covers every chain Edge supports, and no API key is involved.

Network	CAIP id	USDC contract
Ethereum	`eip155:1`	`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
Base	`eip155:8453`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Arbitrum One	`eip155:42161`	`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
Optimism	`eip155:10`	`0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85`
Polygon	`eip155:137`	`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`
Avalanche C-Chain	`eip155:43114`	`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`
Unichain	`eip155:130`	`0x078D782b760474a361dDA0AF3839290b0EF57AD6`
Sonic	`eip155:146`	`0x29219dd400f2Bf60E5a23d13Be72B486D4038894`
World Chain	`eip155:480`	`0x79A02482A880bCE3F13e09Da970dC34db4CD24d1`
Sei EVM	`eip155:1329`	`0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392`
HyperEVM	`eip155:999`	`0xb88339CB7199b77E23DB6E890353E22632Ba630f`
Arc	`eip155:5042`	`0x3600000000000000000000000000000000000000`

You only need a Circle Gateway USDC deposit on one of these chains. The endpoint advertises every chain in its 402 response, and SDK clients pick whichever you’re funded on.

Quickstart

1. Fund a Circle Gateway deposit

Use the Circle Gateway dashboard, or do it directly via the SDK:

import { GatewayClient } from "@circle-fin/x402-batching/client";

const gateway = new GatewayClient({
  chain: "base",                     // any supported chain
  privateKey: process.env.PK as `0x${string}`,
});

await gateway.deposit("1");          // 1 USDC = 200,000 Edge requests

Your deposit takes a few minutes to reflect in Circle’s /v1/balances API after the on-chain transaction confirms.

2. Pay for an Edge request

pay() handles the full 402 → sign → retry flow for you:

const { data, formattedAmount } = await gateway.pay(
  "https://edge.goldsky.com/standard/evm/1",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: { jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] },
  },
);

console.log("signed", formattedAmount, "USDC →", JSON.stringify(data));
// signed 0.005 USDC → {"jsonrpc":"2.0","id":1,"result":"0x1"}

formattedAmount is the amount the SDK signed, which is the top-up amount from the 402 challenge. It is not the cost of the call. Only the first call settles that amount. Each later call is deducted from your balance at $0.000005, and its signed authorization is not settled. Read the x-goldsky-x402-balance response header to see what is left.

That’s it. No Goldsky account, no ?key= query parameter, no invoice. Your wallet address becomes your identity for rate limiting and metrics.

How it works

x402 is an HTTP protocol layered on top of standard requests. The full handshake:

Initial request returns 402

Your client sends an unauthenticated request. Edge responds with HTTP 402 and a body listing every accepted (chain, asset) option. The amount is the top-up amount, not the price of one call. The description says so:

{
  "x402Version": 2,
  "error": "Payment required for this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x87aB362fEF2106d24762289410a18e7c42304C68",
      "description": "Goldsky Edge RPC — prepaid balance, funds ~1000 requests at 5 atomic units each",
      "maxTimeoutSeconds": 604800,
      "extra": {
        "name": "GatewayWalletBatched",
        "version": "1",
        "verifyingContract": "0x77777777dcc4d5a8b6e418fd04d8997ef11000ee"
      }
    }
    // ...one entry per supported chain
  ]
}

Sign an EIP-712 authorization

Your client picks an accepts entry it can satisfy (typically the chain your Gateway deposit lives on) and signs an EIP-712 TransferWithAuthorization message against the GatewayWalletBatched contract from the extra block.

Retry with Payment-Signature header

Your client base64-encodes the signed payload and resends the original request with one extra header:

POST /standard/evm/1
Content-Type: application/json
Payment-Signature: <base64(payment payload)>

Edge tops up your balance or deducts from it

If your wallet has no balance, Edge serves the request and then settles the authorization with Circle’s facilitator. The settled amount is credited to your wallet’s balance, less the cost of this call.If your wallet already has a balance, Edge checks that the authorization’s signature matches your wallet, deducts 5 atomic USDC, and serves the request. It does not send the authorization to Circle. The authorization only proves the request comes from your wallet, and Edge rejects any authorization it has already used.When the balance runs out, the next request settles a new top-up.

Response headers

Every paid response says how it was funded:

Header	Meaning
`x-goldsky-x402-funding`	`pending`: a top-up that Edge settles with Circle after responding. `settled`: a payment Circle settled before the response. `credit`: deducted from your prepaid balance, with no settlement. `unpaid`: served without charging you (see below).
`x-goldsky-x402-balance`	Atomic USDC left in your balance after this request. Present on `credit` responses.
`x-goldsky-x402-amount-required`	On some `unpaid` responses: the amount to authorize so that Edge can charge you again.
`PAYMENT-RESPONSE`	The standard x402 settlement receipt. Present only on `settled` responses.

When Edge returns 402

A signed request gets a 402 with a fresh challenge when:

Circle reports that your Gateway deposit is too low to cover the top-up, or that the authorization’s nonce is already used. After this, Edge answers 402 to your wallet for about 30 seconds without contacting Circle. Top up your Gateway deposit and retry.
The authorization was already used for an earlier request.
The authorization is for less than the price of the request.

If the failure is on Goldsky’s or Circle’s side (for example, Circle is unreachable or rate-limiting Edge), Edge serves the request with x-goldsky-x402-funding: unpaid and does not charge you.

Pay per call instead

To settle every call individually with Circle, with no prepaid balance, send the X-Goldsky-X402-Per-Request: true header. Clients that can’t set headers can use the x402_per_request=true query parameter instead. The 402 challenge then asks for 5 atomic USDC, and each payment settles directly:

const { data } = await gateway.pay(
  "https://edge.goldsky.com/standard/evm/1",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "X-Goldsky-X402-Per-Request": "true",
    },
    body: { jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] },
  },
);

Each call is then one request to Circle’s facilitator, so any rate limit Circle applies to your wallet affects your throughput. If you sign for more than the per-call price, the excess is credited to your balance, but per-request mode does not draw on it.

Auditing your payments

If you compare the authorizations your client signed with the transfers in Circle’s Gateway API, most authorizations will have no matching transfer. This is expected:

Each settled transfer is a top-up of at least $0.005, which pays for about 1,000 calls.
The authorizations signed for later calls are proofs of identity. Edge does not settle them, and it will not settle them later, even though they stay valid until validBefore.
To reconcile, add up your settled transfers and subtract the value of the calls you made at $0.000005 each. The result should match the latest x-goldsky-x402-balance header.

For example, 25 calls on an empty balance produce one $0.005 transfer and 24 unsettled authorizations. Those 25 calls cost $0.000125, and the remaining balance is 4,875 atomic USDC, about 975 calls.

Limits and operational notes

Authorization validity window: Circle Gateway requires the signed authorization’s validBefore to be at least ~4 days in the future. Edge advertises maxTimeoutSeconds: 604800 (7 days) so SDK defaults work out of the box.

Edge RPC

Reference

x402 nanopayments: pay-per-call access to Edge RPC

Copy prompt

Open in Claude

Open in ChatGPT

Open in Perplexity

Pricing

Endpoint

Supported chains for x402 payments

Quickstart

1. Fund a Circle Gateway deposit

2. Pay for an Edge request

How it works

Response headers

When Edge returns 402

Pay per call instead

Auditing your payments

Limits and operational notes

See also

Copy prompt

Open in Claude

Open in ChatGPT

Open in Perplexity

​Pricing

​Endpoint

​Supported chains for x402 payments

​Quickstart

​1. Fund a Circle Gateway deposit

​2. Pay for an Edge request

​How it works

​Response headers

​When Edge returns 402

​Pay per call instead

​Auditing your payments

​Limits and operational notes

​See also

Pricing

Endpoint

Supported chains for x402 payments

Quickstart

1. Fund a Circle Gateway deposit

2. Pay for an Edge request

How it works

Response headers

When Edge returns 402

Pay per call instead

Auditing your payments

Limits and operational notes

See also