---
title: "x402 ledger top-up (agent door)"
method: POST
path: "/v1/x402/topup"
tags: ["Billing"]
---

# x402 ledger top-up (agent door)

`POST /v1/x402/topup`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/x402/topup`
- Auth: none required

The wallet rail for Shroud (Shroud AI plan). Without `X-PAYMENT` the response is a
**402** quote (`x402Version`, `accepts[]` with `payTo`, `maxAmountRequired`, `resource`)
for `amount_usd` (default $1) of USDC on Base. With a signed EIP-3009 `X-PAYMENT`
the facilitator verifies it, the proof is claimed once, the payer wallet's org
ledger is credited in micro-USD, and the facilitator settles.

**Payment is the account.** An unknown wallet's first settled top-up provisions a
shadow org, one Shroud-enabled agent and one `sk-shroud-v1` router key keyed on the
wallet (returned once as `router_key`), after screening the wallet against the OFAC
SDN list (fails closed when the list is missing or stale) and the caller's region
against the custody geofence. Same wallet = same org on every later top-up. The
response always carries a ≤60 s `access_token` for the wallet's agent so the
gateway can serve the paid request immediately. The Shroud gateway drives this for
`Authorization: Bearer x402` requests and relays the quote or the result.

## Headers

- `X-PAYMENT` string

## Request body

- object
  - `amount_usd` integer: Whole dollars to add to the ledger (default 1)

## Response `200`

Credited

- X402TopupResponse
  - `wallet` string, required: Payer address (lower-case)
  - `org_id` string, uuid, required
  - `agent_id` string, uuid, required
  - `credited_micro_usd` integer, required
  - `balance_micro_usd` integer, required
  - `balance_usd` string, required
  - `router_key` string: Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once.
  - `access_token` string, required: A ≤60 s agent token for the wallet's agent (carries the `router_key` claim)
  - `expires_in` integer, required
  - `base_url` string, required: The Shroud gateway
  - `provisioned` boolean, required: True when this top-up created the account

## Other responses

- `402`: Payment required — the quote to sign, or why the payment was refused
- `403`: The wallet is sanctioned or the region is fenced; no account is opened
- `503`: The sanctions list is unavailable (fails closed)

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)