`POST /v1/x402/signup`

Create an account and a Bearer key in one paid call. No browser. No session. The settled payment is the credential.

Public route. There is no walletAddress field. The account belongs to the wallet that signed the payment.

Request

bash

curl -X POST "https://api.pzero.studio/v1/x402/signup" \
  -H "Content-Type: application/json" \
  -d '{ "amountMicroUsdc": 10000000, "keyName": "my-agent", "maxPriceCentsPerDollar": 60 }'

amountMicroUsdc is integer micro-USDC (10000000 = 10 USDC). Not a decimal string. Limits match refill: $1–$1,000 USDC per payment.

Optional fields:

keyName (defaults to x402-signup when omitted)
maxPriceCentsPerDollar (30–80). Omitted → 49. Raise it when first inference answers 503 no_eligible_supply (see PATCH /v1/agent/max-price and GET /v1/capacity).

Challenge

The first call returns 402 with accepts. Sign the EIP-3009 exact payment and retry with X-PAYMENT and a byte-identical body. Payment mechanics match POST /v1/x402/refill. Settled facilitator responses also carry X-PAYMENT-RESPONSE (base64 receipt).

Success

json

{
  "apiKey": "pzero_...",
  "keyName": "my-agent",
  "keyPrefix": "pzero_ab",
  "walletAddress": "0x...",
  "accountId": "...",
  "pendingUsdc": "10.000000",
  "confirmedUsdc": "0.000000",
  "topUpAmountUsdc": "10.000000",
  "maxPriceCentsPerDollar": 60,
  "transaction": "0x...",
  "confirmationBlocks": 6,
  "idempotent": false
}

confirmationBlocks is the configured confirmation depth from the response (do not hardcode it). Store apiKey immediately. The plaintext exists only in this response.

Credit lands pending. Poll GET /v1/agent/me with Authorization: Bearer and the minted key until confirmedUsdc covers the first request.

Situation	Response
Settled and matched on chain	`200` as above
Settled, receipt not visible yet	`200`; credit lands pending and confirms once the block resolves
This settlement was already credited	`200` with `idempotent: true` and no `apiKey`
Wallet already holds 10 active keys	`409` with `credited: true`; payment credited, no key. Revoke one with `DELETE /v1/agent/keys/{id}`, then mint with `POST /v1/agent/keys`
Settled but not credited	`409` with `transaction`; keep the hash, do not pay again. `reconciling: true` means queued credit; `false` needs human recovery

A global fuse on facilitator calls can answer 429 with Retry-After.

If the key is lost

Replaying the same payment is not recovery: already-credited settlements return idempotent: true with no key. The money is on the wallet.

Two ways out, both require the wallet:

Pay a second signup with a fresh settlement (adds balance and mints a key).
Sign in at pzero.studio with that wallet and mint a key in the app.

POST /v1/x402/signup ​

Request ​

Challenge ​

Success ​

If the key is lost ​

Next ​

`POST /v1/x402/signup`

Request

Challenge

Success

If the key is lost

Next