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

# Pay with x402

> Pay per run with a crypto wallet (USDC) using the x402 protocol instead of a prepaid Monid workspace balance.

[x402](https://docs.x402.org) lets you **pay per run with a crypto wallet (USDC)** instead of a prepaid Monid workspace balance. Your client signs an on-chain USDC payment in response to an HTTP `402 Payment Required`, and Monid settles it via a facilitator.

No workspace, no budget, no top-ups — payment is collected on-chain, per run.

<Note>
  x402 covers **execution and retrieval only**. Discovery and inspection still require a normal Monid API key — see [What the API key is still for](#what-the-api-key-is-still-for).
</Note>

## Prerequisites

* An [x402-compatible client](https://docs.x402.org/getting-started/quickstart-for-buyers) (e.g. `@x402/fetch`).
* A wallet funded with **USDC** and **native gas** on your chosen network (see below).

## Supported networks

Monid advertises every supported network in its 402 `accepts` array. Your client picks by matching the network it wants — don't blindly take `accepts[0]`.

| Network       | CAIP-2        | USDC contract                                | Gas token |
| ------------- | ------------- | -------------------------------------------- | --------- |
| Base mainnet  | `eip155:8453` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ETH       |
| Monad mainnet | `eip155:143`  | `0x754704Bc059F8C67012fEd69BC8A327a5aafb603` | MON       |

<Info>
  **Minimum price:** `$0.01`. Monid raises the advertised price to this floor if the run's quote is lower.

  **Metered endpoints** (time-billed) are not available on x402 — x402 is a single fixed upfront payment.
</Info>

## Execute a run

Instead of running with the CLI:

```bash theme={null}
monid run -p <provider> -e <endpoint> -i '<input-json>'
```

Use an x402-compatible client to `POST` to `https://x402.monid.ai/v1/run`:

```bash theme={null}
# with x402-curl or any x402-aware client
x402-curl -X POST https://x402.monid.ai/v1/run \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "pdl",
    "endpoint": "person/enrich",
    "input": {}
  }'
```

The client handles the payment handshake for you: it receives the `402`, signs a USDC authorization, retries the request, and returns the run body once the payment is settled and the run completes.

`input` may carry `{ body, queryParams, pathParams }` — the same shape as the standard `/v1/run` endpoint.

### Response

* **`200`** — run completed. Body includes `runId`, `provider`, `endpoint`, `status`, `output`, `providerResponse`, `price`, `billing`, `billedUnits`, and `pollUrl`. The HTTP status mirrors the provider's own status.
* **`408`** — `TIMED_OUT`. Zero-billed.
* **`400`** — invalid input, or an unsupported (metered) endpoint.

<Tip>
  Save the `runId` and `pollUrl` from every response — you'll need them to retrieve results later.
</Tip>

## Retrieve a run

Instead of getting a run with the CLI:

```bash theme={null}
monid runs get <runId>
```

Use an x402-compatible client to `GET` the `pollUrl` returned by the pay response:

```bash theme={null}
x402-curl https://x402.monid.ai/v1/runs/<runId>
```

This route requires **no payment** — just a Sign-In-With-X (SIWX) signature from the same wallet that paid for the run. Your x402 client handles the SIWX challenge automatically.

### Response

* **`200`** — run status and full body (`output`, `providerResponse`, `price`, `cost`, timestamps).
* **`401`** — signature invalid.
* **`403`** — you are not the wallet that paid for this run.
* **`404`** — run not found.

## List runs

**x402 does not support listing runs.** Access control is per-run wallet ownership, and there's no workspace to scope a list to. Retain each `runId` / `pollUrl` from your pay responses to retrieve them later.

If you need to list runs, use the workspace-scoped [`GET /v1/runs`](/api/runs/list) with an API key.

## What the API key is still for

Even as an x402 user, you need a Monid API key for discovery, inspection, and listing runs.

| Capability         | Endpoint                            | Auth    | Payment       |
| ------------------ | ----------------------------------- | ------- | ------------- |
| Discover providers | `POST api.monid.ai/v1/discover`     | API key | none          |
| Inspect endpoints  | `POST api.monid.ai/v1/inspect`      | API key | none          |
| Execute a run      | `POST x402.monid.ai/v1/run`         | wallet  | USDC on-chain |
| Retrieve a run     | `GET  x402.monid.ai/v1/runs/:runId` | wallet  | none          |
| List runs          | `GET  api.monid.ai/v1/runs`         | API key | n/a           |

Typical loop: **discover / inspect** with your API key → **pay and run** with x402 → **retrieve** with x402.

## Next steps

* [Discover endpoints](/api/discover) with your API key
* [Inspect an endpoint](/api/inspect) before you pay
* [API Reference](/api/overview) for the full `/v1/*` surface