Payment cards over x402

An agent can order prepaid and gift cards through 1Claw and never see the PAN or CVV. The purchase is paid with an outbound x402 payment that the Vault constructs and signs using the agent's own Ethereum signing key, which must hold USDC on Base.

• cards_enabled: the master switch.
• card_max_order_usd and card_daily_limit_usd: enforced atomically over a rolling 24-hour window.
• card_payto_allowlist: which x402 recipients are acceptable.
• card_require_approval: defaults to true, so orders wait for a human.

1. 1

   Set the ordering guardrails on the agent. These bound the purchase, not how the card is later spent.

   bash Copy

   curl -s -X PATCH https://api.1claw.co/v1/agents/$AGENT_ID \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "cards_enabled": true,
       "card_max_order_usd": 25,
       "card_daily_limit_usd": 25,
       "card_require_approval": true
     }'

2. 2

   As the agent, order a card. Idempotency-Key is required.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/agents/$AGENT_ID/cards/order \
     -H "Authorization: Bearer $AGENT_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "kind": "prepaid", "amount_usd": 25, "country": "US" }'

3. 3

   Because approval is required you get a 202 with status awaiting_approval, and no payment has been made yet.

   json Copy

   { "status": "awaiting_approval", "card_id": "...", "approval_id": "..." }

4. 4

   A human approves: in the dashboard, the mobile app, or by one-click email link. Only then does the x402 payment run.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/approvals/$APPROVAL_ID/decide \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -d '{"decision":"approved"}'

5. 5

   Check status. The card monitor polls the provider and fills in last4, expiry, and balance.

   bash Copy

   1claw card list
   1claw card get <card-id>   # always masked to last4

Where this goes wrong in practice. Card ordering combines an agent, a payment rail and a bearer instrument, and each seam has its own failure.

• Order caps are mistaken for spend caps. The guardrails bound what an agent may buy, not what the resulting card can be spent on. Once funded, the balance is outside their reach.
• Idempotency keys are reused or omitted. The key is required on order, and getting it wrong means either a rejected request or a duplicate purchase depending on which direction you err.
• Orphaned payments are ignored. The monitor flags rows stuck in ordering as orphaned_payment, which means money moved and no card resulted. That needs reconciliation, not a filter.
• Reveal policy is enabled for convenience. Per-card reveal for agents exists for narrow cases, and enabling it broadly puts a PAN one injection away from a context window.
• Card lifecycle is unmanaged. Cards accumulate with residual balances unless void_after is set and depleted cards are cleaned up.