API Reference

Integrate AgentPay in five minutes

One scoped key per agent. Issue a charge request, get an approve/deny verdict back. The policy engine runs server-side; your agent only sees the result.

Authentication

Every request to the AgentPay API authenticates with a bearer token — the API key issued when you create a wallet. Keys are shown once at creation; rotate them anytime from the wallet detail page.

bash

Authorization: Bearer ap_test_xxxxxxxxxxxxxxxxxxxxxxxx

Test keys are prefixed ap_test_; production keys with ap_live_. Do not commit either to source control.

Charge an agent wallet

Send a single POST to the charge endpoint. The policy engine evaluates per-transaction cap, monthly budget, and vendor allowlist before approving. Approved charges are committed to the ledger and reduce the wallet's remaining budget.

POST/api/agent/transactions

Request body

param	type	required	description
`vendor`	string	yes	Domain or merchant identifier (e.g. openai.com)
`amount_cents`	integer	yes	Charge amount, in cents (e.g. 1200 = $12.00)
`idempotency_key`	string	no	Re-sending the same key returns the prior result
`metadata`	object	no	Free-form JSON, stored on the transaction

Example

bash

curl -X POST https://agentpay-jade.vercel.app/api/agent/transactions \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "openai.com",
    "amount_cents": 1200,
    "idempotency_key": "msg_4197"
  }'

Approved response (200)

json

{
  "transaction_id": 4197,
  "status": "approved",
  "policy_matched": "vendor_allowlist",
  "denial_reason": null,
  "vendor": "openai.com",
  "amount_cents": 1200,
  "remaining_budget_cents": 348800,
  "anomalies_flagged": 0,
  "created_at": "2026-05-01T15:42:11.000Z"
}

Denied response (402)

json

{
  "transaction_id": 4198,
  "status": "denied",
  "policy_matched": "vendor_allowlist",
  "denial_reason": "Vendor \"evil.com\" is not on the allowlist",
  "vendor": "evil.com",
  "amount_cents": 9900,
  "remaining_budget_cents": 348800,
  "anomalies_flagged": 0,
  "created_at": "2026-05-01T15:42:14.000Z"
}

Policy evaluation order

Wallet active? Paused wallets reject everything.
Per-transaction cap. If set, charges over the cap are denied.
Budget remaining. If set, charges that would push the wallet over budget are denied.
Vendor allowlist. If set, only allowlisted vendors are approved. Empty allowlist = allow any vendor.

Each check returns the matching policy in policy_matched so you can debug exactly why a charge was denied.

Anomaly alerts

Approved charges are also evaluated for anomalies and flagged on the wallet's alerts inbox. Medium- and high-severity alerts are pushed to the wallet owner's email automatically.

alert_type	severity	trigger
`velocity_spike`	high	5+ transactions in a 60-second window
`high_value_charge`	medium	Single charge consumes ≥50% of remaining budget
`new_vendor`	low	First transaction with a vendor this wallet has paid

Code samples

Node.js / TypeScript

async function charge(vendor: string, amountCents: number) {
  const res = await fetch("https://agentpay-jade.vercel.app/api/agent/transactions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AGENTPAY_API_KEY!}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ vendor, amount_cents: amountCents }),
  });
  return res.json();
}

Python

python

import os, requests

def charge(vendor: str, amount_cents: int):
    return requests.post(
        "https://agentpay-jade.vercel.app/api/agent/transactions",
        headers={"Authorization": f"Bearer {os.environ['AGENTPAY_API_KEY']}"},
        json={"vendor": vendor, "amount_cents": amount_cents},
    ).json()

Ready to provision a wallet?

Get started free →