Crow — Agent Payment Service

# 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

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

Response:
```json
{
  "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.

```bash
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:

```bash
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:
```bash
# 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

```bash
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:**
```json
{"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

```bash
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.

```bash
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](https://nightmarket.ai) 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
```