> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 nanopayments

> Pay-per-request access to Edge RPC over the x402 HTTP protocol, no account required

export const AGENT_PROMPT = `Use Goldsky Edge RPC to make EVM JSON-RPC calls. Pay per call via the x402 protocol, no Goldsky account or API key required.

Endpoint pattern: https://edge.goldsky.com/standard/evm/{chainId}
Discover all chains Edge serves: GET https://edge.goldsky.com (returns JSON list with id, alias, blockTimeMs, state).

Pay-per-request: $5 per million requests (5 atomic USDC = $0.000005 per call), settled gaslessly through Circle Gateway. Supported chains for x402 payments: Ethereum (eip155:1), Base (eip155:8453), Arbitrum One (eip155:42161), Optimism (eip155:10), Polygon (eip155:137), Avalanche (eip155:43114), Unichain (eip155:130), Sonic (eip155:146), World Chain (eip155:480), Sei EVM (eip155:1329), HyperEVM (eip155:999).

One-time setup: deposit USDC into Circle Gateway on any of the supported chains. Use https://developers.circle.com/gateway, or the SDK:

import { GatewayClient } from "@circle-fin/x402-batching/client";
const gateway = new GatewayClient({ chain: "base", privateKey: process.env.PK });
await gateway.deposit("1"); // 1 USDC = 200,000 Edge requests

Make a paid request. The SDK handles the full 402 → sign → retry handshake:

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

Docs: https://docs.goldsky.com/edge-rpc/capabilities/x402`;

export const ENCODED_PROMPT = encodeURIComponent(AGENT_PROMPT);

<CardGroup cols={2}>
  <div
    onClickCapture={(e) => {
  if (typeof navigator !== "undefined" && navigator.clipboard) {
    e.preventDefault();
    e.stopPropagation();
    navigator.clipboard.writeText(AGENT_PROMPT);
  }
}}
  >
    <Card title="Copy prompt" icon="copy" href="#" />
  </div>

  <Card title="Open in Claude" icon="https://mintcdn.com/goldsky-38/ZGItD__kHOxygOLb/images/logos/icon-claude.svg?fit=max&auto=format&n=ZGItD__kHOxygOLb&q=85&s=03d140b3922818ce4710109268b60b7f" href={`https://claude.ai/new?q=${ENCODED_PROMPT}`} width="16" height="16" data-path="images/logos/icon-claude.svg" />

  <Card title="Open in ChatGPT" icon="https://mintcdn.com/goldsky-38/ZGItD__kHOxygOLb/images/logos/icon-chatgpt.svg?fit=max&auto=format&n=ZGItD__kHOxygOLb&q=85&s=34f8245d14a73b48e649eed7a232c718" href={`https://chatgpt.com/?q=${ENCODED_PROMPT}`} width="16" height="16" data-path="images/logos/icon-chatgpt.svg" />

  <Card title="Open in Perplexity" icon="https://mintcdn.com/goldsky-38/ZGItD__kHOxygOLb/images/logos/icon-perplexity.svg?fit=max&auto=format&n=ZGItD__kHOxygOLb&q=85&s=bad0886723c9e2c2bc2bfb3485cfea3d" href={`https://www.perplexity.ai/?q=${ENCODED_PROMPT}`} width="15" height="16" data-path="images/logos/icon-perplexity.svg" />
</CardGroup>

Edge RPC accepts pay-per-request payments over the [x402 protocol](https://www.x402.org/), settled through [Circle Gateway](https://developers.circle.com/gateway). Fund a USDC balance once with Circle and pay per call against any supported chain, with no Goldsky account, no API key, and no invoice.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant Agent as Your agent
  participant Edge as Edge RPC
  participant Circle as Circle Gateway
  Agent->>Edge: POST /standard/evm/{chain}
  Edge-->>Agent: 402 + accepted (chain, asset) list
  Note over Agent: Sign EIP-712 authorization<br/>against Gateway contract
  Agent->>Edge: POST + Payment-Signature header
  Edge->>Circle: Settle 5 atomic USDC ($0.000005)
  Circle-->>Edge: Settlement OK
  Edge-->>Agent: 200 + JSON-RPC result
```

x402 is designed for autonomous agents. SDK clients handle the full handshake transparently.

## Pricing

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

Each call debits 5 atomic USDC (\$0.000005) from your Circle Gateway balance. Settlement is gasless on your side, and Circle batches settlements on Goldsky's side.

## 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:

```bash theme={null}
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

You can pay over x402 on any chain Circle Gateway currently advertises. The 11 networks below mirror the live list at [`https://gateway-api.circle.com/v1/x402/supported`](https://gateway-api.circle.com/v1/x402/supported); Edge serves additional chains that aren't yet in this list, and those still require a regular API key.

| 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` |

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](https://developers.circle.com/gateway), or do it directly via the SDK:

```ts theme={null}
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:

```ts theme={null}
const { data, formattedAmount, transaction } = 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("paid", formattedAmount, "USDC →", JSON.stringify(data));
// paid 0.000005 USDC → {"jsonrpc":"2.0","id":1,"result":"0x1"}
```

That's it. No Goldsky account, no secret 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:

<Steps>
  <Step title="Initial request returns 402">
    Your client sends an unauthenticated request. Edge responds with HTTP 402 and a body listing every accepted (chain, asset) option:

    ```json theme={null}
    {
      "x402Version": 2,
      "error": "Payment required for this resource",
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:8453",
          "amount": "5",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x87aB362fEF2106d24762289410a18e7c42304C68",
          "maxTimeoutSeconds": 604800,
          "extra": {
            "name": "GatewayWalletBatched",
            "version": "1",
            "verifyingContract": "0x77777777dcc4d5a8b6e418fd04d8997ef11000ee"
          }
        }
        // ...one entry per supported chain
      ]
    }
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Retry with Payment-Signature header">
    Your client base64-encodes the signed payload and resends the original request with one extra header:

    ```http theme={null}
    POST /standard/evm/1
    Content-Type: application/json
    Payment-Signature: <base64(payment payload)>
    ```

    Edge forwards the payment to Circle's facilitator for settlement, then proxies the RPC request to upstream providers and returns the response with HTTP 200.
  </Step>
</Steps>

A successful settlement debits your Circle Gateway balance and emits a settlement receipt back in the response headers. Failed settlements (insufficient balance, expired authorization, etc.) return a 402 again so you can pick a different chain or top up.

## 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.

## See also

* [x402 protocol spec](https://www.x402.org/)
* [Circle Gateway docs](https://developers.circle.com/gateway)
* [`@circle-fin/x402-batching` SDK](https://www.npmjs.com/package/@circle-fin/x402-batching)

Can't find what you're looking for? Reach out to us at [support@goldsky.com](mailto:support@goldsky.com) for help.