Costillery Docs

Receipt intelligence for AI agents

Costillery automatically captures payment receipts from your AI agents' API calls using MPP and x402 protocols. Gain full visibility into agent spend across services like OpenAI, Anthropic, Grok, and more. One line of code to integrate.

Quick Start

Install the SDK and wrap your fetch in seconds. Two modes available:

Mode 1: API Key (Teams)

npm install costillery

import { Costillery } from 'costillery';

const ledger = new Costillery({ apiKey: 'your_key' });
const wrappedFetch = ledger.wrapFetch(fetch);

Mode 2: MPP (Agents — No Signup)

import { Costillery } from 'costillery';

// No API key needed — agents pay $0.002/receipt via MPP
const ledger = new Costillery({ wallet: privateKey, mode: 'mpp' });
const wrappedFetch = ledger.wrapFetch(fetch);

MPP uses Tempo mainnet (chain 4217) with pathUSD. No account required. Agents pay per receipt.

SDK Reference

Costillery(options) — API Key mode

apiKey

Required for API key mode. Your Costillery API key from app.costillery.com.

endpoint

Default: 'https://api.costillery.com'. Custom API endpoint.

projectTag

Optional project label for spend categorization.

departmentTag

Optional department label.

Costillery(options) — MPP mode

wallet

Required for MPP mode. The agent's Ethereum private key (hex string). The wallet pays $0.002 per receipt via Tempo mainnet.

mode

Set to 'mpp' for MPP mode. No API key required.

endpoint

Default: 'https://api.costillery.com'.

Methods

ledger.wrapFetch(fetch)

Wraps a fetch implementation to automatically capture MPP Payment-Receipt headers and x402 Payment-Response bodies. Returns the wrapped fetch function.

ledger.wrapAxios(axiosInstance)

Wraps an Axios instance for automatic receipt capture. Returns the wrapped instance.

ledger.submitReceipt(opts)

Manually submit a receipt. Options: { receipt_raw, service_url, protocol, metadata }. receipt_raw is base64-encoded receipt.

API Reference

API Key Authentication

Authorization: Bearer <api_key>

MPP Authentication

MPP endpoints use payment as authentication. No API key required. The payment credential must match the requested wallet address.

Submit receipts: POST /v1/receipts — $0.002 / receipt
Query spending: GET /v1/wallet/:address/summary — $0.005 / query
Query receipts: GET /v1/wallet/:address/receipts — $0.005 / query

MPP 402 Challenge Format

When a payment is required, the server returns 402 Payment Required with:

WWW-Authenticate: Payment amount=<units>, currency=<token_address>, chain=<chain_id>, recipient=<address>

Example:
amount=2000 (=$0.002 in smallest units)
currency=0x20c0000000000000000000000000000000000000 (pathUSD)
chain=4217 (Tempo mainnet)
recipient=0xB90C0eFda8A234275108C2bD68F56233D5ED4639

The agent's SDK signs a transaction to pay the amount, then resubmits with the payment credential. pathUSD is a USDC-pegged stablecoin on Tempo.

POST /v1/receipts

MPP: $0.002 / receipt. No API key needed. Include MPP payment credential in resubmit. Returns { accepted, receipt_ids } plus spend summary for MPP users.

API key: Submit with Authorization: Bearer <key>. Returns { accepted, receipt_ids }.

GET /v1/wallet/:address/summary

MPP: $0.005 / query. Query spending breakdown for a wallet. Must include valid MPP payment credential. Wallet in credential must match URL path (403 otherwise).

{
  "wallet": "0xABC...",
  "period": "2026-03",
  "total_spend_usd": 34.82,
  "total_receipts": 412,
  "services": [
    { "name": "OpenAI", "category": "ai", "spend": 12.40, "count": 89 },
    { "name": "Parallel", "category": "search", "spend": 8.20, "count": 205 }
  ],
  "settlement_rails": { "crypto_tempo": "61%", "fiat_stripe": "24%", "crypto_base": "15%" },
  "daily_trend": [
    { "date": "2026-03-25", "spend": 1.20, "receipts": 14 },
    { "date": "2026-03-26", "spend": 2.47, "receipts": 31 }
  ]
}

GET /v1/wallet/:address/receipts

MPP: $0.005 / query. Paginated receipt list for a wallet. Filters: from, to, service, page, limit. Wallet in payment credential must match URL path (403 otherwise).

Returns: { receipts, total, page, limit, wallet }

POST /v1/auth/claim-wallet

Claim historical MPP receipts into a full account. Submit wallet address + EIP-191 signed message + signature. Creates org if new, returns API key. { wallet_address, signature, message }

Returns: { api_key, organization_id, receipts_claimed }

GET /v1/receipts

API key only. Paginated receipt list. Filters: from, to, service, project, page, limit.

GET /v1/reports/summary

API key only. Aggregated spending summary for the organization.

GET /v1/billing/status

API key only. Returns plan, limits, Stripe subscription status, and MPP config.

GET /v1/health

Health check. No auth required.

Protocol Reference

MPP

Payment-Receipt header for automatic capture. Present in response headers from MPP-compatible services.

x402 V1

WWW-Authenticate challenge + Payment-Response in response body. Standard HTTP 402 flow.

x402 V2

Same as V1 but with updated header names (X-Payment-Challenge, etc.).

Webhook / Alert Integration

The alerts system allows configuring spend thresholds. Alert configs are stored and history in alerts tables.

GET /v1/alerts/config

Get alert settings.

POST /v1/alerts/config

Update alert settings.

Pricing & Plans

Feature	Free	Pro	Enterprise
Receipts/mo	5,000	100,000	Unlimited
Retention	30 days	1 year	Unlimited
CSV export	Yes	Yes	Yes
QuickBooks / Xero	No	Yes	Yes
Spend alerts	Daily only	Advanced + new service	Advanced + new service
Team members	1	5	Unlimited
MPP support	Yes	Yes	Yes
Price	$0	$49/mo	$199/mo

SDK Examples

Example 1: Basic (MPP protocol)

import { AgentLedger } from 'costillery';
const ledger = new AgentLedger({ apiKey: 'your_key' });
globalThis.fetch = ledger.wrapFetch(globalThis.fetch);

Example 2: x402 with Axios

import { wrapAxios } from 'costillery';
const ledger = wrapAxios(axios.create(), { apiKey: 'your_key' });

Example 3: Manual submission

await ledger.submitReceipt({
  receipt_raw: base64Receipt,
  service_url: 'https://api.openai.com/v1/chat/completions',
  protocol: 'mpp',
  metadata: { project: 'research', department: 'eng' }
});

Example 4: Check spend

const summary = await fetch('https://api.costillery.com/v1/dashboard/summary', {
  headers: { Authorization: 'Bearer your_key' }
}).then(r => r.json());
console.log('Total spent:', summary.total_amount_usd);

Service Directory

The SDK automatically enriches receipts with service names by matching URLs against the Costillery service directory. URLs not in the directory are labeled "unknown".

Claim Account

MPP users can claim their receipts into a full Costillery account by signing a message with their wallet. Visit costillery.com/claim.

1. Open costillery.com/claim?wallet=0xABC...
2. Click "Sign to Claim"
3. Your wallet signs the message (EIP-191 personal_sign)
4. POST /v1/auth/claim-wallet verifies the signature
5. Org created (or existing found), API key returned, receipts backfilled
6. Use the API key in dashboard or SDK

The signed message proves wallet ownership. Claims are rate-limited to 5 per wallet per hour. The API key is returned only once — save it.

Support / Contact

Email: hi@costillery.com
GitHub: github.com/wytcab/costillery
Dashboard: https://app.costillery.com