API v2

LimitLayer API — Developer Reference

Financial guardrails for AI agents. Control budgets, enforce merchant rules, require approvals, and get real-time spend decisions.

Base URL: https://api.limitlayer.ioSwagger: /docsReDoc: /redoc

1. Authentication

Authenticate every request with your API key. You can find or create API keys in the LimitLayer Dashboard under Settings → API Keys.

Send the key in either header:

http

X-API-Key: ll_aBcDeFgH...          ← preferred
Authorization: Bearer ll_aBcDeFgH... ← also accepted

⚠️ Never expose your API key in client-side code or public repositories. All calls to LimitLayer should be made from your server.

Wallets, agents, policies, approvals, webhooks, and other management features are configured through the LimitLayer Dashboard. This reference covers only the API endpoints your application calls at runtime.

2. Transactions

The core flow: an agent requests a transaction → policies are evaluated → decision is returned.

Transaction Lifecycle

CREATED → [REQUIRES_APPROVAL] → APPROVED → PAYMENT_CONFIRMED
                                          → PAYMENT_FAILED (wallet reversed)
         → DENIED
         → EXPIRED  (approval window elapsed)

Tip: After receiving requires_approval, poll GET /transactions/{transaction_id}/status until the status changes to APPROVED, DENIED, or EXPIRED. Approvals are managed by your team in the LimitLayer Dashboard.

3. Decline Normalisation

Send a raw wallet-provider decline and get back a normalised category, recommended action, and risk score.

Request fields

Field	Type	Required	Description
`wallet_provider`	string	Yes	Which wallet returned the error
`raw_response`	object	Yes	The raw error/decline JSON — any shape
`agent_id`	string	Yes	Your LimitLayer agent ID
`transaction.amount`	float	No	Transaction amount (for analytics)
`transaction.merchant`	string	No	Merchant name (for analytics)

4. Outcomes & Retry Advisory

Report payment outcomes to LimitLayer and receive intelligent retry recommendations based on historical patterns.

5. Error Reference

All errors follow this shape: { "detail": "Human-readable error message" }

Status	Meaning
`400`	Bad request — validation failed or invalid input
`401`	Unauthenticated — missing or invalid credentials
`403`	Forbidden — authenticated but insufficient role/access
`404`	Resource not found or doesn't belong to your org
`409`	Conflict — e.g. duplicate wallet name
`410`	Gone — approval request has expired
`422`	Unprocessable entity — request body schema violation
`423`	Locked — wallet is frozen, transactions blocked
`429`	Rate limit exceeded
`500`	Internal server error

Common 401 causes

API key not in X-API-Key header or Authorization: Bearer header
API key is_active = false or status = revoked
API key expires_at in the past

Common 403 causes

Tenant role insufficient for this operation (see permission matrix)
Cross-tenant request blocked (path org_id ≠ caller's org_id)
Organisation inactive or soft-deleted

Last updated: March 2026