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

# Buyer Quickstart: Pay for an API

> Install the metal-agent CLI, create and fund the agent's key on testnet, and make a paid request that settles on Metal

With the `metal-agent` CLI you create the agent's key, fund it, and
make a paid request over [x402](https://docs.metalntwx.com/agents/x402-on-metal.md) to Metal's demo
seller, which charges `0.01 *USDZ` for `GET /quote`.

## 1. Install the CLI

```bash theme={null}
npm install -g @metalntwx/metal-agent@0.3.3
```

## 2. Create the agent's key

```bash theme={null}
metal-agent key create
```

```text theme={null}
address 0x0DACfCc0c8604B125f0ca70BcB03e679aD701802
keyfile /Users/you/.metal-agent/key.json
```

This is the agent's own key, and the address is where it pays from. The
key file holds the private key in the clear, so treat it as the secret.
If the key file already exists, `key create` keeps it and answers that it
`already holds a key`; its `address` field is the address.

## 3. Fund the key

Sign in to the [Metal console](https://console-testnet.metalntwx.com), the
same sign-in that gives you an [RPC endpoint](https://docs.metalntwx.com/network/endpoints.md), then open
**Faucet** and fund the address. Each grant tops it up to 100
`*USDZ`, and grants are limited per user. Without a sign-in, ask the
public faucet:

```bash theme={null}
metal-agent fund <address> --network testnet
```

```text theme={null}
funded 0x0DACfCc0c8604B125f0ca70BcB03e679aD701802 with 100 *USDZ from the testnet faucet
transaction <funding transaction hash>
explorer https://testnet.metalntwx.com/tx/<funding transaction hash>
```

Pass `--network testnet` to every command that touches the chain. The
[public faucet](https://faucet.metalntwx.com) grants each IP address ten
times a UTC day, once a minute, so everyone behind one address shares them,
out of 1,000 grants a day for every client, the Console included. If it
refuses, you get the reason and what to do next. The Console's Faucet page
uses the same faucet: when the faucet is down, retry later.

## 4. Pay

```bash theme={null}
metal-agent pay https://x402-demo-testnet.metalntwx.com/quote --network testnet
```

```text theme={null}
nonce <payment nonce>
status 200
payer 0x0DACfCc0c8604B125f0ca70BcB03e679aD701802
payee <demo seller address>
amount 0.01 *USDZ
network eip155:63825
transaction <settlement transaction hash>
explorer https://testnet.metalntwx.com/tx/<settlement transaction hash>
header <name>: <value>
body {"quote":"Every payment leaves a trace on chain.","issuedAt":"2026-09-24T20:26:41.458Z"}
```

Response headers the seller sends appear as `header <name>: <value>` lines
before `body`, except those `pay` hides, such as `content-type` and `date`.

The facilitator submitted the transfer and paid the gas. A payment it
refuses exits with its [reason](https://docs.metalntwx.com/agents/facilitator.md#refusal-reasons).

`pay` caps a purchase at 1 `*USDZ` by default; pass `--max <usdz>` to
raise it for one command. To let an agent pay from your Metal account within
limits it cannot change, see [Mandates](https://docs.metalntwx.com/agents/mandates.md).

## 5. Check the settlement

Open the `explorer` URL to see the settlement, or use `status` with an
[endpoint](https://docs.metalntwx.com/network/endpoints.md) of your own:

```bash theme={null}
metal-agent status <transaction> --network testnet --rpc-url <your endpoint>
```

```text theme={null}
transaction <settlement transaction hash>
status success
block <block number>
submitter <facilitator address>
gas <gas used> at <fee> per gas, paid in *USDZ
transfer 0.01 *USDZ from 0x0DACfCc0c8604B125f0ca70BcB03e679aD701802 to <demo seller address>
```

## Pay from code

To make the same payment from TypeScript, use `createMetalPaymentClient`
from `@metalntwx/metal-pay`. The same 1 `*USDZ` cap applies unless you set
`maxAmount`. Set `AGENT_PRIVATE_KEY` to the `privateKey` field of the key
file:

```typescript theme={null}
import { privateKeyToAccount } from "viem/accounts";
import { createMetalPaymentClient } from "@metalntwx/metal-pay";

const { fetchWithPayment } = createMetalPaymentClient({
  account: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`),
  network: "testnet",
});
const response = await fetchWithPayment("https://x402-demo-testnet.metalntwx.com/quote");
```

> [card] [Accept agent payments](https://docs.metalntwx.com/agents/quickstart-accept.md)
>
> The seller's side: a route that charges for this agent's requests.

> [card] [Facilitator](https://docs.metalntwx.com/agents/facilitator.md)
>
> Endpoints, limits, refusal reasons and retries.


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