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

# RPC Endpoints

> Create an RPC endpoint of your own in the Metal console, or let an agent buy one over x402: a URL that is its own credential, serves JSON-RPC over HTTP, and draws on prepaid credit

Every request to the testnet goes through an endpoint of your own, which
serves every method the gateway supports over HTTP. It is what
`metal-agent status`, Foundry and a backend use. Create one in the console,
or let an [agent buy its own](#an-endpoint-for-your-agent).

## 1. Create an endpoint

Sign in at the [Metal console](https://console-testnet.metalntwx.com); \$50
of [credit](https://docs.metalntwx.com/network/credits.md) lands at your first sign-in, with no card. To
buy more later, add the Airwallex sandbox test card `4035 5010 0000 0008`,
any future expiry and CVC, on the Billing page. Then create an endpoint with
a name and a network:

```text theme={null}
https://rpc-testnet.metalntwx.com/v1/<endpoint id>
```

The id is the credential: anyone holding the URL sends requests on your
credit. Keep it out of client-side code and rotate it from the endpoint's
page when it leaks. For a client that can send a header, add an Endpoint
Secret, turn on "Require a credential", and send the secret as HTTP Basic
authentication, with the endpoint id as
the username and the secret as the password, in the `Authorization` header.

## 2. Send a request

```bash theme={null}
export METAL_RPC_URL=https://rpc-testnet.metalntwx.com/v1/<endpoint id>
cast chain-id --rpc-url "$METAL_RPC_URL"
# 63825
```

The gateway serves a set of the `eth_*`, `net_*` and `web3_*`
[methods](https://docs.metalntwx.com/reference/json-rpc/overview.md) and some of Metal's own; it holds
no keys, so sign locally and submit with `eth_sendRawTransaction`.

## An endpoint for your agent

Your agent can use the RPC without your endpoint. The bare
`https://rpc-testnet.metalntwx.com/v1` responds to a `POST` with `402`, an
[x402](https://docs.metalntwx.com/agents/x402-on-metal.md) challenge for \$1 of credit, and an agent
holding `*USDZ` pays it from its own wallet:

```bash theme={null}
metal-agent pay https://rpc-testnet.metalntwx.com/v1 --network testnet \
  --method POST --body '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

The response carries the call's output, and its `rpc-aas-endpoint` header
names the endpoint the payment opened, owned by the agent's address. The agent sends
every later call there, with no payment, as any client does. Your account
and your endpoint are never involved, so the agent cannot draw on your
credit.

When that endpoint's credit runs out it responds `402` again, and the same
command, at its URL or at the bare `/v1`, tops it up by another \$1; see
[Credits](https://docs.metalntwx.com/network/credits.md#top-up-as-an-agent). `GET` on either URL returns
the price. An address is handed one endpoint, however often it pays, and a
payment already settled buys nothing a second time. These endpoints have no
console login.

## Limits

| | Per endpoint |
| - | - |
| Request body | 1 MiB; a batch holds 100 requests |
| Response | 16 MiB; the chain answers within 10 seconds |
| In flight | 512 requests, per gateway instance |
| Throughput | About 1,000 base-rate requests a second, with a burst of 2,000, per gateway instance |
| Credit a day | About \$150 |

Past the in-flight or throughput limit, or while the chain is too busy to
take the call, the gateway answers `429` with `Retry-After`; a body
or batch over its limit gets `413`. Once the
day's credit is used it answers `402` until midnight UTC; with no
credit left, `402`, which an agent can
[pay](https://docs.metalntwx.com/network/credits.md#top-up-as-an-agent). The console's Usage page shows
each endpoint's requests by method, with the charge for each.

> [card] [Credits](https://docs.metalntwx.com/network/credits.md)
>
> What a request costs, and topping up, by card or as an agent.

> [card] [JSON-RPC](https://docs.metalntwx.com/reference/json-rpc/overview.md)
>
> Every method the gateway serves, with examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.