Documentation

Quick Start

Get running in under 5 minutes. Create an account, issue your first agent card, and attach a spending policy.

POST /api/v1/actions/check

Evaluate whether an agent's spend is permitted under its current policy. Call this before your agent executes any purchase or payment.

curl -X POST https://capped.ai/api/v1/actions/check \
  -H "Authorization: Bearer lim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "action_type": "purchase",
    "amount_usd": 120,
    "reason": "Compute instance for data pipeline"
  }'

Request body

Response

{
  "status": "approved",            // approved | blocked | requires_approval | reduced
  "decision_id": "dec_xyz789",
  "reason": "All policy checks passed",
  "requires_human_approval": false,
  "allowed_amount_usd": null,      // set when status is "reduced"
  "policy_checks": [
    { "rule": "per_txn_limit", "result": "pass", "message": "$120 ≤ $500 limit" },
    { "rule": "daily_volume",  "result": "pass", "message": "$320 of $1,000 daily cap" }
  ]
}

Status values

POST /api/v1/actions/:id/execute

After a requires_approval decision is approved by a human in the Approvals dashboard, call this to record it as executed.

curl -X POST https://capped.ai/api/v1/actions/dec_xyz789/execute \
  -H "Authorization: Bearer lim_your_api_key"

Python example

Use this helper to gate any spend in your agent code before the card is charged.

import requests

API_KEY = "lim_your_api_key"
BASE   = "https://capped.ai"

def check_spend(agent_id, amount_usd, reason=""):
    """Check if a purchase is allowed under the agent's spending policy."""
    res = requests.post(
        f"{BASE}/api/v1/actions/check",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "agent_id":    agent_id,
            "action_type": "purchase",
            "amount_usd":  amount_usd,
            "reason":      reason,
        },
    )
    return res.json()

result = check_spend(
    "agent_abc123",
    amount_usd=120,
    reason="EC2 instance for data pipeline",
)

if result["status"] == "approved":
    # proceed with payment / API call
    pass
elif result["status"] == "requires_approval":
    print("Queued for human review:", result["decision_id"])
elif result["status"] == "reduced":
    print("Capped at:", result["allowed_amount_usd"])
else:
    print("Blocked:", result["reason"])

LangChain tool

Wrap capped.ai as a LangChain tool so your agent automatically checks policy before any spend.

from langchain.tools import tool
import requests

@tool
def spend_with_policy(amount_usd: float, reason: str = "") -> str:
    """Gate a purchase through the capped.ai policy engine before charging the card."""
    res = requests.post(
        "https://capped.ai/api/v1/actions/check",
        headers={"Authorization": "Bearer lim_your_api_key"},
        json={
            "agent_id":    "agent_abc123",
            "action_type": "purchase",
            "amount_usd":  amount_usd,
            "reason":      reason,
        },
    ).json()

    if res["status"] == "blocked":
        return f"Spend blocked: {res['reason']}"
    elif res["status"] == "requires_approval":
        return f"Queued for approval (id: {res['decision_id']})"
    elif res["status"] == "reduced":
        return f"Capped: proceed with ${res["allowed_amount_usd"]} instead"

    return f"Approved: ${amount_usd} approved"

Real-time authorization webhook

capped.ai evaluates every card authorization in real time before it clears. When an agent's card is used, the network calls our authorization webhook and capped.ai responds with approved: true or approved: false within 2 seconds based on the active policy.

# Authorization webhook (preconfigured — no setup required):
https://capped.ai/api/webhooks/authorize

# capped.ai evaluates every authorization in real time:
# 1. Check per-transaction limit
# 2. Check daily volume cap
# 3. Check approval threshold
# 4. Respond approved: true or false

No additional code needed — the webhook is preconfigured when you create an agent card.

Spending policy reference

Configure policies in the dashboard under Policies. Each policy is attached to one agent card.

tradingMode values

Connect your first agent

Get an AI agent making purchases through a capped.ai virtual card in under 15 minutes.

Before you start: Complete KYB verification in your account settings. Card provisioning is gated on approval.

export AGENT_CARD_NUMBER="4111111111111234"
export AGENT_CARD_EXPIRY="12/28"
export AGENT_CARD_CVV="123"

import { LimitMD } from '@capped/sdk'
import { tool } from '@langchain/core/tools'
import { z } from 'zod'

const limitmd = new LimitMD({ apiKey: process.env.LIMIT_MD_API_KEY })

const purchaseTool = tool(
  async ({ amount, merchant }) => {
    const token = await limitmd.tokens.create({
      cardId: process.env.LIMIT_MD_CARD_ID,
      amount,
      merchant,
      expiresIn: 300,
    })
    return { token: token.value, expiry: token.expiry }
  },
  {
    name: 'make_purchase',
    description: "Make a purchase using the agent's virtual card",
    schema: z.object({
      amount: z.number().describe('Amount in cents'),
      merchant: z.string(),
    }),
  }
)

GET /api/agents/:id — Balance & card state

Fetch an agent's virtual balance and card status. Use this to display remaining budget or confirm a card is active before making purchases.

curl https://capped.ai/api/agents/agent_abc123 \
  -H "Authorization: Bearer lim_your_api_key"

Response

{
  "agent": {
    "id": "agent_abc123",
    "name": "research-agent",
    "mode": "paper",
    "status": "active",
    "virtualBalanceUsd": 4832.50,
    "cardStatus": "open",
    "stripeCardId": "ic_xyz789",
    "policies": [{ "perTransactionLimitUsd": 500, "dailyVolumeLimitUsd": 1000 }]
  }
}

Key fields

Freeze / unfreeze a card

# Freeze
curl -X PATCH https://capped.ai/api/agents/agent_abc123/card \
  -H "Authorization: Bearer lim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "action": "freeze" }'

# Unfreeze
curl -X PATCH https://capped.ai/api/agents/agent_abc123/card \
  -H "Authorization: Bearer lim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "action": "unfreeze" }'

GET /api/agents/:id/transactions — Transaction history

List the 50 most recent card transactions for an agent, newest first. Works in both sandbox and production.

curl https://capped.ai/api/agents/agent_abc123/transactions \
  -H "Authorization: Bearer lim_your_api_key"

Response

{
  "transactions": [
    {
      "id": "txn_abc123",
      "agentId": "agent_abc123",
      "amount": 12000,
      "currency": "USD",
      "merchant": "AWS Marketplace",
      "status": "approved",
      "declineReason": null,
      "createdAt": "2026-06-19T10:22:14Z"
    }
  ]
}

Generating test transactions (sandbox)

Use the sandbox base URL (https://api.sandbox.capped.ai) and send POST /api/v1/actions/check — each call creates a synthetic transaction that appears in this list immediately. Sandbox data resets every 24 hours; no real money moves.

Transaction statuses

Decline codes

When a card transaction is declined, the API returns a machine-readable code. Find the code in Dashboard → Transactions → [transaction] → Decline reason or in the error response body.

{
  "error": {
    "code": "SPEND_LIMIT_EXCEEDED",
    "message": "Transaction of $150.00 exceeds the per-transaction limit of $100.00.",
    "transactionId": "txn_xyz789"
  }
}

Authentication troubleshooting

Every capped.ai API request requires a Bearer token in the Authorization header.

Authorization: Bearer lim_<64 hex characters>

Key format

Production base URL: https://api.capped.ai
Sandbox base URL: https://api.sandbox.capped.ai
A sandbox key sent to the production URL returns 401.

Common errors

# Wrong — no "Bearer" prefix
curl -H "Authorization: lim_yourkey" https://capped.ai/api/v1/actions/check

# Wrong — "Token" instead of "Bearer"
curl -H "Authorization: Token lim_yourkey" https://capped.ai/api/v1/actions/check

# Correct
curl -H "Authorization: Bearer lim_yourkey" https://capped.ai/api/v1/actions/check

Rotating keys safely

Incident response

If you see transactions you did not authorize, or suspect your API key has been leaked, act immediately.

curl -X PATCH https://capped.ai/api/agents/CARD_ID/card \
  -H "Authorization: Bearer lim_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "action": "freeze" }'

Identity verification (KYB)

capped.ai is a financial product. Before you can provision your first virtual card, your business must pass Know Your Business (KYB) verification. This is a regulatory requirement and takes 1–3 business days.

How to complete KYB

KYB status

While KYB is pending, you can use the sandbox environment. No KYB required for sandbox.

Spend limit types

capped.ai gives you three independent controls over how much a virtual card can spend. All three apply simultaneously.

A transaction is approved only if it passes all configured limits. Omitting a dimension means no limit is enforced for that dimension.

Configure all three limits in the dashboard: Dashboard → Cards → [select card] → Edit Limits. Changes take effect immediately.

Webhook integration

capped.ai sends webhook events to your endpoint when transactions occur, cards change state, or other account events happen.

import crypto from 'crypto'

function verifyWebhook(body: string, signature: string, signingSecret: string): boolean {
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(body, 'utf8')
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  )
}

app.post('/webhooks/limitmd', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-capped-signature'] as string
  if (!verifyWebhook(req.body.toString(), sig, process.env.LIMIT_MD_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature')
  }
  const event = JSON.parse(req.body.toString())
  res.status(200).send('ok')
  // process event async...
})

Webhook event types

Funding and auto-reload

capped.ai operates on a prepaid model. Your account balance is drawn down as your agents make purchases.

Adding funds

Auto-reload

Auto-reload prevents your agents from stalling due to a low balance. When your balance drops below a threshold you set, capped.ai automatically pulls from your linked bank account via ACH.

Best practice: Set your auto-reload threshold to at least 3× your average daily spend so the 1–3 day ACH settlement window is covered.

// Check agent balance via GET /api/agents/:id
const res = await fetch('https://capped.ai/api/agents/agent_abc123', {
  headers: { 'Authorization': 'Bearer lim_yourkey' },
})
const { agent } = await res.json()
// agent.virtualBalanceUsd — remaining paper balance in USD

Team management

Invite teammates to your capped.ai account and control what each person can do using roles.

Invite a team member via Dashboard → Settings → Team → Invite Member. Role changes take effect immediately. Removing a team member revokes their access immediately — rotate any API keys they created separately.

Agent mode

The mode field on an agent — and tradingMode on its attached policy — controls how the policy engine treats every incoming action. Set it when you create an agent or update one at any time.

live_disabled enforcement: when policy.tradingMode is live_disabled, the policy engine returns status: "blocked" for any request where action_type is trade. Non-trade actions — payment, api_spend, wallet_transfer — bypass this check and are evaluated normally against all other policy rules.

Create and update agent mode

const BASE = 'https://capped.ai'
const API_KEY = process.env.CAPPED_API_KEY

// Create an agent in paper mode (safe default for development)
const res = await fetch(`${BASE}/api/agents`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'research-agent',
    mode: 'paper',          // paper | approval_only | live_disabled
    virtualBalanceUsd: 5000,
  }),
})
const { agent } = await res.json()
// agent.id, agent.mode === "paper"

// Gate every trade behind a human before going live
await fetch(`${BASE}/api/agents/${agent.id}`, {
  method: 'PATCH',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ mode: 'approval_only' }),
})

// Immediately halt all trading while keeping payments live
await fetch(`${BASE}/api/agents/${agent.id}`, {
  method: 'PATCH',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ mode: 'live_disabled' }),
})

Rate limits

Support

Questions, bugs, or feedback — email hello@capped.ai. Enterprise support includes a dedicated Slack channel.

For billing questions: billing@capped.ai. For security incidents: security@capped.ai.