---
name: agentpay
description: Lean AgentPay skill for init, fund, balance, spend, cards, and expiration.
---

# AgentPay

Use AgentPay when an agent needs to spend money online from a prefunded balance.

Base URL: `https://agent-pay.sh`

Public routes:

- `POST /init`
- `GET /balance`
- `POST /fund`
- `POST /spend`
- `GET /cards`
- `GET /expiration`
- `POST /expiration`
- `GET /start`
- `GET /agent`
- `GET /skill`

Rules:

- `POST /init` is the only time the API key is returned
- `POST /fund` requires a minimum funding amount of $20.00; suggest $50 as the default when asking a human how much to fund
- `POST /spend` is the only time card details are returned
- `POST /spend` immediately reserves funds from balance
- New cards default to a 20 minute self-destruct timer
- `POST /expiration` can set the timer to any whole number of minutes from 1 to 1440
- Cards self-destruct after first use or when the expiration timer is reached
- Leftover or unused card balance is credited back automatically
- `GET /cards` never returns PAN, CVV, or billing details again

## Agent Onboarding Flow

When an agent is given AgentPay for the first time:
1. Call `POST /init` to create an account — save the API key immediately
   > By calling POST /init, you accept the AgentPay Terms of Service at https://agent-pay.sh/terms
2. Ask the human how much they want to fund (minimum $20, suggest $50 as default)
3. Call `POST /fund` with the amount — give the checkout URL to the human
4. Wait for the human to complete payment, then poll `GET /balance` until funds arrive
5. Once funded, call `POST /spend` with the amount needed and a memo describing the purchase
6. Save the returned card details (PAN, CVV, expiry) — they are only shown once
7. Use the card to make the purchase

## CLI

Install: `npm install -g agentpay-cli`

```
agentpay init              # Create account, save API key locally
agentpay balance           # Show available balance
agentpay fund <amount>     # Create funding checkout link
agentpay spend <amount>    # Create single-use virtual card
agentpay cards             # List previous cards (redacted)
agentpay expiration [min]  # Get or set default card expiry
```

The CLI stores your API key at `~/.agentpay/config.json` after init. Use `--json` flag for machine-readable output.

Flow:

1. Call `POST /init` (or run `agentpay init`)
2. Save the API key immediately
3. Call `POST /fund` with an amount
4. Give the returned checkout URL to a human
5. Poll `GET /balance` until funds arrive
6. Call `POST /spend` with `amount` and optional `memo`
7. Use the returned one-time card immediately
8. Repeat fund -> balance -> spend as needed

Examples:

Create account:
```bash
curl -sS -X POST https://agent-pay.sh/init
```

Create funding checkout:
```bash
curl -sS -X POST https://agent-pay.sh/fund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'
```

Create one-time card:
```bash
curl -sS -X POST https://agent-pay.sh/spend \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "memo": "buy API credits"}'
```

Set default expiration:
```bash
curl -sS -X POST https://agent-pay.sh/expiration \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minutes": 15}'
```