Crow — Agent Payment Service

Crow gives your AI agent a wallet to pay for APIs and services autonomously — within spending rules set by the wallet owner. All interaction is via curl / HTTP requests to https://api.crowpay.ai.

Two payment methods:

• x402 (USDC on Base) — for APIs that return HTTP 402 Payment Required
• Credit card (Stripe) — for merchants, subscriptions, API credits

Dashboard: https://crowpay.ai/dashboard

When to Use This Skill

• Agent gets an HTTP 402 Payment Required response
• Agent needs to pay for an API, buy credits, or pay a merchant
• User wants to set up an agent wallet with spending rules
• User asks about CrowPay, Crow, or agent payments
• User wants their agent to buy something on the internet

---

Setup — Get a Wallet and API Key

curl -X POST https://api.crowpay.ai/setup \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "apiKey": "crow_sk_abc123...",
  "walletAddress": "0x1234...abcd",
  "claimUrl": "https://crowpay.ai/claim/xyz789",
  "fundingInstructions": "Send USDC on Base to 0x1234...abcd"
}

Three things to do after setup:

1. Save the apiKey immediately — it is shown only once and cannot be retrieved later
2. Tell the user to visit the claimUrl to create their account and set spending rules
3. Fund the wallet: send USDC on Base to walletAddress, or add a credit card in the dashboard

All subsequent requests need this header:

X-API-Key: crow_sk_abc123...

---

Decision Tree

Agent needs to pay for something?
│
├── Got an HTTP 402 from an API? (x402 / USDC)
│   │
│   └── curl POST /authorize  ← pass the full 402 response body
│       ├── 200 → Got signed payload. Retry original request with payment-signature header.
│       ├── 202 → Needs human approval. Poll GET /authorize/status every 3s.
│       └── 403 → Spending rules blocked it. Tell the user.
│
└── Paying a merchant with credit card?
    │
    └── curl POST /authorize/card  ← pass amount, merchant, reason
        ├── 200 → Got sptToken. Use it to pay via Stripe.
        ├── 202 → Needs human approval. Poll GET /authorize/status every 3s.
        └── 403 → Spending rules blocked it. Tell the user.

---

Endpoints

POST /setup — Create wallet + API key

No auth required.

curl -X POST https://api.crowpay.ai/setup \
  -H "Content-Type: application/json" \
  -d '{"network": "eip155:8453"}'

network is optional (defaults to Base mainnet). Response contains apiKey, walletAddress, claimUrl.

---

POST /authorize — Pay for an x402 API (USDC)

When you hit an API and get a 402 Payment Required response, forward the entire response body to Crow:

curl -X POST https://api.crowpay.ai/authorize \
  -H "X-API-Key: crow_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "paymentRequired": {
      "x402Version": 2,
      "resource": {"url": "https://api.example.com/v1/data"},
      "accepts": [{
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "1000000",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0xRecipientAddress",
        "maxTimeoutSeconds": 60,
        "extra": {"name": "USDC", "version": "2"}
      }]
    },
    "merchant": "ExampleAPI",
    "reason": "Fetching data for user task",
    "platform": "Claude MCP",
    "service": "Premium data API"
  }'

Required fields:

• paymentRequired — the full 402 response body from the API
• merchant — name of the service (wallet owner sees this)
• reason — why the payment is needed (wallet owner sees this)

Optional context fields (recommended):

• platform — which agent/platform is making the request (e.g. "Claude MCP", "LangChain")
• service — what service/product the payment is for (e.g. "Weather API call", "Premium data")

200 → Auto-approved. Response is a signed payment payload. To retry the original request:

# Base64-encode the entire response and put it in the payment-signature header
PAYMENT=$(echo -n '<full JSON response>' | base64 -w0)
curl https://api.example.com/v1/data -H "payment-signature: $PAYMENT"

202 → Needs human approval. Response contains approvalId. Poll for status (see below).

403 → Denied. Spending rules blocked it. Do not retry with same params.

See references/x402-flow.md for the complete end-to-end walkthrough.

---

POST /authorize/card — Pay a merchant with credit card

curl -X POST https://api.crowpay.ai/authorize/card \
  -H "X-API-Key: crow_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1000,
    "merchant": "OpenAI",
    "reason": "GPT-4 API credits",
    "platform": "Claude MCP",
    "service": "GPT-4 API credits"
  }'

Required fields:

• amountCents — amount in cents (1000 = $10.00)
• merchant — merchant name
• reason — why the payment is needed

Optional fields:

• currency — defaults to "usd"
• paymentMethodId — specific card to use (uses default card if omitted)
• merchantStripeAccount — Stripe Connect account ID if applicable
• platform — which agent/platform is making the request (e.g. "Claude MCP", "LangChain")
• service — what service/product the payment is for (e.g. "GPT-4 credits", "API subscription")

200 → Auto-approved:

{"approved": true, "sptToken": "spt_...", "transactionId": "..."}

Use the sptToken to pay the merchant. Expires in 1 hour.

202 → Needs human approval. Poll for status.

403 → Denied. Spending rules blocked it.

See references/card-payments.md for full details.

---

GET /authorize/status — Poll for approval

curl "https://api.crowpay.ai/authorize/status?id=APPROVAL_ID" \
  -H "X-API-Key: crow_sk_abc123..."

Poll every 3 seconds. Do not poll faster.

Status in response	What to do
"pending"	Keep polling
"signing"	Keep polling (approved, generating payload)
Response has payload field	Done — use the signed payload to pay
Response has sptToken field	Done — use token for card payment
"denied"	Stop. Owner rejected the payment.
"timeout"	Stop. Approval window expired.
"failed"	Stop. Error during signing.

---

POST /settle — Report x402 settlement

After the x402 facilitator settles your payment on-chain, report it. Idempotent — safe to call multiple times.

curl -X POST https://api.crowpay.ai/settle \
  -H "X-API-Key: crow_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"transactionId": "...", "txHash": "0x..."}'

Not needed for card payments (Stripe webhooks handle this automatically).

---

Key Numbers

Type	Format	Example	Dollar value
USDC (x402)	Atomic units, 6 decimals	1000000	$1.00
USDC (x402)	Atomic units, 6 decimals	100000	$0.10
Card	Cents	100	$1.00
Card	Cents	1000	$10.00

• Network: Base mainnet (eip155:8453)
• USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Default Spending Rules

Auto-created when wallet is claimed:

• Per-transaction limit: $25
• Daily limit: $50
• Auto-approve threshold: $5 (above this → human must approve)

Owners customize these in the dashboard.

References

For deeper walkthroughs with complete curl examples and all edge cases:

• references/api-reference.md — Complete API reference: every endpoint, every field, every response code with curl examples
• references/x402-flow.md — End-to-end 402 payment walkthrough with curl
• references/card-payments.md — Credit card payment walkthrough with curl
• references/error-handling.md — All error codes, retry strategy, polling best practices

Finding Services to Pay For

Use Nightmarket to discover paid APIs your agent can call. Every Nightmarket service uses x402 — Crow handles the payments automatically.

Install the Nightmarket skill:

npx skills add https://github.com/Fallomai/skills --skill nightmarket