---
title: "Create a payment challenge"
method: POST
path: "/x402/challenges"
tags: ["Payments"]
---

# Create a payment challenge

`POST /x402/challenges`

Create an x402 payment challenge (the payee side of a payment). The
`pay_to` address is resolved server-side from your registered default
payout address for the network, never from the request. The response
carries the `nonce_binding` and `payment_requirements` the payer needs to
sign; hand the whole challenge object to the payer (for example in an
email reply). Amounts are in token base units (USDC has 6 decimals, so
`"10000"` is 0.01 USDC).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `amount` string, required — Amount to collect, in token base units. USDC has 6 decimals, so `"10000"` is 0.01 USDC.
  - `network` 'base' | 'base-sepolia', required
  - `payer_org` string, uuid — The org id allowed to pay this challenge (on-net binding). Optional.
  - `expires_in` integer — Seconds until the challenge expires. Defaults to 3600.
  - `resource` string, uri — Optional URL identifying what is being paid for. Defaults to a synthetic `x402:challenge:<id>` identifier.
  - `description` string — Optional human-readable description of the payment.

## Response `201`

Challenge created

- object
  - `success` true, required
  - `data` object, required
    - `id` string, uuid, required
    - `status` 'pending' | 'settling' | 'settled' | 'failed' | 'expired', required
    - `network` 'base' | 'base-sepolia', required
    - `asset` string, required — Token contract address (checksummed).
    - `amount` string, required — Amount in token base units.
    - `pay_to` string, required — The payee's resolved payout address (checksummed).
    - `payer_org` string, nullable — The org id bound as payer, if one was set at creation.
    - `resource` string, nullable
    - `description` string, nullable
    - `nonce_binding` object, required — The interaction binding the payer hashes into the EIP-3009 nonce (`deriveEip3009Nonce`). Pinning the nonce to this binding is what lets an x402 payment ride asynchronous transports safely: a replayed challenge can't redirect funds and a signed payment can't settle twice.
      - `interaction_id` string, required — Interaction id, including its `@domain` part.
      - `challenge_step_id` string, uuid, required
      - `challenge_nonce` string, required — 32 random bytes as 64 lowercase hex chars.
    - `settle_tx` string, nullable — On-chain settlement transaction hash once settled.
    - `settled_at` string, date-time, nullable
    - `failure_reason` string, nullable
    - `expires_at` string, date-time, required
    - `created_at` string, date-time
    - `payment_requirements` object — The x402 `PaymentRequirements` the payer signs over. Field names are x402's native camelCase, preserved byte-for-byte.
      - `scheme` string, required — The x402 settlement scheme. Always `exact` for v1.
      - `network` 'base' | 'base-sepolia', required
      - `maxAmountRequired` string, required — Amount in token base units.
      - `payTo` string, required — The payee's resolved payout address (checksummed).
      - `asset` string, required — The token contract address (checksummed). USDC.
      - `resource` string
      - `description` string
      - `maxTimeoutSeconds` integer
      - `extra` object, required — The token's load-bearing EIP-712 domain params. `name` differs by chain (Base mainnet USDC is `USD Coin`, Base Sepolia is `USDC`); a wrong value produces a signature the verifier rejects.
        - `name` string, required
        - `version` string, required

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `403` — Authenticated caller lacks permission for the operation
- `422` — The request was well-formed but could not be processed. For Payments this covers a missing payout address, a failed payment verification, a spend-policy decline, or an expired challenge; `error.code` distinguishes them.
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) · [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primitive/primitive-api/revisions/c2299d28022c/schema)