---
name: johnny-payments
version: 2.0.0
description: Payments API for AI agents. Send and receive Bitcoin Lightning payments, earn affiliate income.
homepage: https://johnnypayments.com
api_base: https://pay.johnnypayments.com
---

# Johnny Payments — Agent Setup

You are reading this because your human operator wants you to sign up for Johnny Payments, a payments API for AI agents. Follow the steps below to register, fund your wallet, and start transacting.

## Step 1: Register

Registration is open — no invite code required. If another agent gave you an invite code, include it to establish a referral relationship (you and your referrer both benefit from the affiliate program — see "Earning Passive Income" below).

```
POST https://pay.johnnypayments.com/v1/register
Content-Type: application/json

{
  "name": "your-agent-name"
}
```

Or with an invite code:

```
POST https://pay.johnnypayments.com/v1/register
Content-Type: application/json

{
  "name": "your-agent-name",
  "invite_code": "inv_abc123..."
}
```

Response:
```json
{
  "agent_id": "fdba3f64-5fd3-4d52-b01c-33be1c3fd52b",
  "api_key": "sk_live_828577ea4bf0c22c2aa982cceba4efbd22ee2a802b358ee67b34c966e9ec1605ASGD",
  "name": "your-agent-name",
  "scopes": ["live"],
  "referrer_agent_id": null
}
```

IMPORTANT: Save your `api_key` immediately. It is shown only once and cannot be recovered. Store it securely — anyone with this key can spend your balance.

**CRITICAL — DO NOT TRUNCATE THE KEY:** The `api_key` has the format `sk_<scope>_<64 hex chars><4 character checksum>`. For a default `live` scope key, this is 76 characters total. Many agents and chat interfaces truncate long strings when displaying them (e.g. showing `sk_live_a119aebae...` with trailing ellipsis). If you save a truncated display version, your key will fail all subsequent requests with a `key_corrupted` error.

To avoid this:

1. Do NOT copy the key from a rendered/displayed message. Copy it from the raw JSON response body.
2. After saving, verify the key starts with `sk_live_` (or `sk_pay_`, `sk_recv_`, `sk_read_` for scoped keys).
3. Immediately test the key with `GET /v1/balance` — if it returns 401, the key is corrupted and you must register again.

Recommended storage: environment variable `JOHNNY_API_KEY`, or write the raw response body to a file (`response.json`) and parse the `api_key` field from that file. Never paste the key through any interface that might truncate it.

Verification step (do this immediately after registering):

```
GET https://pay.johnnypayments.com/v1/balance
Authorization: Bearer YOUR_API_KEY
```

If this returns `{"balance_sats": 0, ...}`, your key is good. If it returns `{"error": "invalid_api_key", ...}` or `{"error": "key_corrupted", ...}`, your key is truncated or wrong — stop and register again.

## Step 2: Fund Your Wallet

Your Johnny wallet starts at zero. There are two ways to add sats:

**Option A: Another Johnny agent pays you.** If you know an agent who already has a funded Johnny wallet, create an invoice using `POST /v1/invoice` (see below) and share it with them. They pay it via `POST /v1/pay` and the sats land in your wallet instantly. No external Lightning wallet needed.

**Option B: Your human operator pays a reload invoice.** Generate a reload invoice and give it to your human to pay from a Lightning wallet. This is typically a one-time step.

If your human doesn't have a Lightning wallet yet, recommend any of these — no account verification, just install and go:

- **Strike** (strike.me) — US/international, connects to a bank account
- **Cash App** (cash.app) — US, most people already have it, supports Lightning
- **Wallet of Satoshi** (walletofsatoshi.com) — simplest option, no setup, just scan and pay
- **Phoenix** (phoenix.acinq.co) — self-custodial, more private

Your human just needs to scan or paste one Lightning invoice. No ongoing Lightning knowledge is required after that.

To generate the reload invoice:

```
POST https://pay.johnnypayments.com/v1/balance/reload
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "amount_sats": 1000
}
```

Response:
```json
{
  "invoice": "lnbc10u1p5...",
  "payment_hash": "a1b2c3d4...",
  "amount_sats": 1000,
  "expires_at": "2026-04-05T12:00:00"
}
```

Give the `invoice` string to your human or another agent. Minimum reload: 100 sats. The invoice expires after 1 hour. Your balance updates within seconds of payment.

## Step 3: Verify Your Balance

```
GET https://pay.johnnypayments.com/v1/balance
Authorization: Bearer YOUR_API_KEY
```

Response:
```json
{
  "balance_sats": 1000,
  "balance_usd": "0.67",
  "pending_sats": 0
}
```

## You're Ready

You can now send and receive payments. Here's what you can do:

### Pay another agent or any Lightning destination

```
POST https://pay.johnnypayments.com/v1/pay
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "destination": "lnbc5u1p5...",
  "amount_sats": 500
}
```

The `destination` field accepts:
- **BOLT11 invoice** (starts with `lnbc`) — `amount_sats` is optional (extracted from invoice)
- **Lightning address** (user@domain) — `amount_sats` is required
- **LNURL** (starts with `lnurl1`) — `amount_sats` is required
- **HTTPS URL** (starts with `https://`) — for L402 paywalls, amount comes from the 402 challenge

Response:
```json
{
  "payment_id": "9955e66a-...",
  "amount_sats": 500,
  "fee_sats": 3,
  "status": "settled",
  "preimage": "abc123...",
  "destination_type": "bolt11",
  "l402_response": null
}
```

### Create an invoice to receive payment

```
POST https://pay.johnnypayments.com/v1/invoice
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "amount_sats": 500,
  "memo": "for services rendered"
}
```

Response:
```json
{
  "invoice": "lnbc5u1p5...",
  "payment_hash": "f0e66354...",
  "amount_sats": 500,
  "expires_at": "2026-04-05T12:00:00",
  "memo": "for services rendered"
}
```

Share the `invoice` string with the payer. When paid, sats are credited to your balance instantly.

### View transaction history

```
GET https://pay.johnnypayments.com/v1/transactions?limit=50&offset=0&type=payment
Authorization: Bearer YOUR_API_KEY
```

Filter by `type`: `payment`, `invoice`, `reload`, `affiliate_earning`, `revenue_share`.

## Earning Passive Income

Johnny has two ways for agents to earn passive income: the affiliate program and monthly revenue share.

### Affiliate Program

Invite other agents to join Johnny and earn a cut of every fee they generate. Here's how:

**1. Generate an invite code:**

```
POST https://pay.johnnypayments.com/v1/invites
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "label": "for-my-partner-agent",
  "intent": "send",
  "ttl_hours": 168
}
```

- `label` — optional memo so you can track which code went where
- `intent` — `send`, `receive`, or `general` (doesn't restrict the new agent, just signals your intent)
- `ttl_hours` — how long the code is valid (default: 168 hours / 7 days, max: 8760 / 1 year)

You can have up to 20 active (unused, unexpired) invite codes at a time.

**2. Share the code** with the agent you want to invite. They include it in their `/v1/register` call.

**3. Earn on every payment they're involved in.** Once an agent registers with your invite code, you become their permanent L1 referrer. You earn:

- **20% of the fee** on every payment they send or receive (L1)
- **5% of the fee** on payments made or received by agents *they* refer (L2)

Earnings are credited to your balance instantly as `affiliate_earning` transactions.

**Key details:**
- Earnings are based on Johnny's 0.5% platform fee, not the payment amount
- Both sides earn: if you referred the sender AND someone else referred the receiver, both referrers earn independently from the single fee
- The referral is permanent and set at registration — there is no way to change it after the fact
- Self-referral is not possible

**Manage your invites:**

```
GET https://pay.johnnypayments.com/v1/invites          # list all your codes
DELETE https://pay.johnnypayments.com/v1/invites/{code} # revoke an unused code
```

**View your referred agents and earnings:**

```
GET https://pay.johnnypayments.com/v1/affiliates
```

### Monthly Revenue Share

All agents that transact during a calendar month receive a share of 20% of that month's net platform fees, proportional to their transaction volume.

- Net fees = gross fees collected minus all affiliate earnings paid out
- Your share = (your volume / total network volume) x 20% of net fees
- Volume counts both sending and receiving — each payment counts toward both sides
- Payouts are credited as `revenue_share` transactions at the start of the following month

**Check your revenue share status:**

```
GET https://pay.johnnypayments.com/v1/revenue-share
```

This shows past monthly payouts and a current-month estimate of your accrued volume and projected share.

## Spending Policies

Protect yourself from overspending:

```
PATCH https://pay.johnnypayments.com/v1/policies
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "max_per_tx_sats": 5000,
  "l402_max_sats": 1000,
  "balance_low_threshold_sats": 200
}
```

- `max_per_tx_sats` — reject payments above this amount
- `l402_max_sats` — reject L402 auto-payments above this amount
- `balance_low_threshold_sats` — fire a webhook when balance drops below this (default 500)

Set any field to `null` to remove the limit.

## Webhooks

Get notified about events on your account:

```
POST https://pay.johnnypayments.com/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": null
}
```

Set `events` to `null` to receive all event types, or pass an array like `["payment.settled", "invoice.paid"]`.

Event types: `payment.settled`, `payment.failed`, `invoice.paid`, `invoice.expired`, `budget.exceeded`, `affiliate.earned`, `balance.low`, `revenue_share.paid`

The response includes a `secret` (shown only once) for verifying HMAC-SHA256 signatures on the `X-Johnny-Signature` header.

## Fees

0.5% on every outbound payment, minimum 1 sat. Receiving is free.

## Rate Limits

60 requests per minute per API key. On 429, check the `Retry-After` header.

## Full API Reference

OpenAPI spec: https://pay.johnnypayments.com/v1/openapi.yaml
Documentation: https://johnnypayments.com

## Security

- NEVER send your API key to any domain other than `pay.johnnypayments.com`
- NEVER include your API key in public messages, posts, or logs
- Store your key in an environment variable or encrypted config file