GET /api/v1/balance

Returns the authenticated user billing summary.

Example

curl "https://tinypostcard.com/api/v1/balance" \
  -H "Authorization: Bearer $TINYPOSTCARD_API_KEY"

Response

{
  "user": {
    "id": "cuid",
    "email": "user@example.com",
    "name": "Avery",
    "tokenBalance": 42,
    "hasStripeCustomer": true,
    "hasSavedCard": true
  }
}

GET /api/v1/token-packs

Returns available token packages used on Billing. No authentication required.

curl "https://tinypostcard.com/api/v1/token-packs"

Response includes id, amountCents, tokens, and label for each package.

POST /api/v1/token-pack-checkout

Creates a hosted Stripe Checkout URL for an API-key-authenticated agent.

curl -X POST "https://tinypostcard.com/api/v1/token-pack-checkout" \
  -H "Authorization: Bearer $TINYPOSTCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"packId":"pack_10"}'

Response

{
  "url": "https://checkout.stripe.com/c/...",
  "checkoutSessionId": "cs_live_...",
  "mode": "stripe",
  "pack": {
    "id": "pack_10",
    "amountCents": 1000,
    "tokens": 8,
    "currency": "usd"
  },
  "payment": {
    "provider": "stripe_checkout",
    "linkWalletSupported": true,
    "linkSkillUrl": "https://link.com/skill.md"
  }
}

Related endpoint

GET /api/v1/me is useful for API key debugging and includes isAdmin.

Link wallet for agents

Token packs are purchased through hosted Stripe Checkout. Link wallet for agents can approve the agent’s checkout spend when Link is enabled and eligible.

Recommended agent flow:

1. Read https://link.com/skill.md.
2. Authenticate with Link.
3. Call POST /api/v1/token-pack-checkout for the selected token pack.
4. Open the returned hosted Checkout URL and use Link approval.
5. Complete the hosted checkout after the user approves.
6. Re-check GET /api/v1/balance.

Agents must not request or store raw card credentials.

Stripe agentic payments

For guest one-off postcard sends, agents can use Stripe shared payment tokens instead of token packs. Use the MCP prepare_postcard_send tool to get the current amount and STRIPE_NETWORK_BUSINESS_PROFILE, issue a Link-backed shared payment token, then call POST /api/v1/postcards/send with agenticPayment.sharedPaymentToken.

Generic Link agents can also use the HTTP 402 machine-payment flow: submit the final guest send payload without payment, read WWW-Authenticate: Payment, approve a shared-payment-token spend request, and retry with Authorization: Payment ....

Token-pack checkout is still the best flow for authenticated users who want a reusable tinypostcard balance.

The current Link CLI manifest does not expose a shipping-address tool. For sender/return address, use authenticated tinypostcard defaults/contacts when available; otherwise ask the human directly.