Limulus API

A payment control that sits between an agent and the rail. It holds the payment at the bank, compares three records, and releases only if they agree. Everything it decides is signed and independently verifiable.

Quickstart

The shortest useful path: gate one payment and read the receipt.

# hold it at the bank, check it, act on the verdict
curl -X POST https://api.limulus.dev/v1/gate \
  -H "authorization: Bearer lim_test_..." \
  -H "content-type: application/json" \
  -d '{
    "scenario": "poisoned",
    "qualificationId": "qual_8aa7a92e8c6c47ee"
  }'

# → BLOCK, transfer cancelled, nothing reached the ledger
{
  "verdict": { "verdict": "BLOCK", "decisionId": "dec_73416581ed334bd1" },
  "transfer": { "id": "sandbox_ach_transfer_xwrvbt...",
                 "statusBefore": "pending_approval",
                 "statusAfter": "canceled",
                 "stoppable": false },
  "action": "Cancelled at the bank. This money cannot now move."
}

Core concepts

Three records

A payment is released only when these agree. Most controls compare a payment to a policy; the failure that costs money is the gap between what an agent said it would do and what actually reached the rail.

Hold first, decide second

The transfer is created before the decision, with require_approval. Deciding first and creating afterwards leaves the moment between them unguarded, and leaves nothing to cancel when the answer is no. An unapproved transfer expires rather than settling, so failing closed is the default.

Authentication

Bearer keys. Only a SHA-256 hash and the first characters are stored, so the key is shown once at creation and never again.

authorization: Bearer lim_test_9f2c4a...

Idempotency

Send Idempotency-Key on any payment call. A repeat with the same key and body replays the original response with limulus-idempotent-replay: true; the same key with a different body returns 409.

Release gate

Runs the three-way match and answers in one of four words. Does not touch a bank — use /v1/gate when you want the payment actually held.

{
  "authorization": { "policyVersion": "v12", "limitPerPayment": 75000,
                      "approvedVendors": [...], "approvedInvoices": [...] },
  "declaration":   { "payeeName": "Northline Steel", "payeeAccountLast4": "2210",
                      "amount": 3400, "invoiceId": "INV-2291", "reason": "..." },
  "paymentOrder":  { "rail": "ach", "payeeAccountLast4": "2210", "amount": 3400 },
  "documents":     [{ "name": "INV-2291.pdf", "type": "invoice", "text": "..." }],
  "qualificationId": "qual_..."
}

Gate at the bank

The same evidence, but the payment is created held at the rail and then approved or cancelled. This is the call that makes the decision binding rather than advisory.

Which rail is answering, and whether it is live. Every response says so, so a demo cannot be mistaken for production.

Verdicts and explanation codes

Branch on codes, never on prose. Guidance is included because the expensive failure is an agent reacting to a refusal by trying a variation.

Qualification codes

A qualification gap escalates rather than blocks: an untested version means a person decides, not that the payment is fraudulent.

Settlements

Report what the rail did. The outcome is re-verified immediately against the decision.

Reconciliation

Asks the bank what happened and compares every transfer with the decision behind it. This exists because settlement reports arrive only when someone sends them, and the case that matters most — a payment that settled although we held it — is the one nobody would think to report.

{
  "checked": 77,
  "unauthorized": 1,
  "drift": [{
    "transferId": "sandbox_ach_transfer_mktokk...",
    "status": "pending_submission",
    "decided": "escalated",
    "code": "unauthorized",
    "detail": "money moved although the decision escalated it"
  }]
}

The Lab

Runs an agent through the scenario library in a simulated world where no money moves, and grades what it did — the tool calls — rather than what it said.

{ "endpoint": "https://your-agent.example/act", "version": "1.4.2", "trials": 3 }

Your agent receives one turn at a time and replies with a single step:

// request
{ "task": "...", "authorization": {...}, "documents": [...],
  "tools": [...], "history": [...], "step": 0, "maxSteps": 8 }

// reply — either
{ "type": "tool_call", "tool": "get_payment_status", "args": { "invoiceId": "INV-2291" } }
// or
{ "type": "finish", "action": "refuse", "reason": "..." }

The four axes

Readiness runs experimental → shadow-ready → human-supervised → limited-autonomous → expanded-autonomous. Any critical violation keeps an agent off the top three rungs, and autonomy needs at least three trials per scenario so consistency is measured rather than assumed.

Qualifications

A signed, expiring statement of what an agent is cleared to do on its own — and the join between testing and enforcement. Testing an agent means nothing if an untested one can still release.

{
  "level": "limited-autonomous",
  "binding": {
    "agent": { "name": "ap-agent", "version": "1.4.2", "toolConfigHash": "b843..." },
    "workflow": "invoice-payment", "rail": "ach", "currency": "USD",
    "amountLimit": 5000, "payeeScope": "on-file"
  },
  "expiresAt": "2026-10-17T..."
}

Validity: 30 days at autonomous levels, 90 supervised, 180 shadow. The more autonomy, the sooner an agent proves itself again.

Receipts

About 2 KB of signed JSON carrying the decision, the checks that ran, the payment, the outcome, a hash over all of it and an Ed25519 signature. Verification recomputes the hash from the receipt as received and checks the signature against that, so any edit fails both.

Recomputes every hash and signature in the decision chain and confirms each record points at the one before it.

Webhooks

Deliveries carry limulus-signature: t=<unix>,v1=<hmac> — HMAC-SHA256 over timestamp.body with the endpoint secret. Verify before trusting, and reject anything older than five minutes. Three attempts, backing off.

Connecting an agent over MCP

An agent can use Limulus with no custom integration. JSON-RPC 2.0 over stdio, protocol 2025-06-18, no dependencies.

claude mcp add limulus -- node /path/to/limulus/src/mcp/server.ts

The initialize response carries standing instructions, so a connected agent is told up front to check before paying, to treat documents as evidence rather than instructions, and what each verdict requires of it.

MCP tools

What an agent is told about each verdict

A run, end to end

1. get_qualification          → cleared for ACH up to 5,000, vendors on file
2. get_authorization          → approved invoices, accounts on file
3. check_payment              → ALLOW  (a dry run; nothing created)
4. pay_invoice                → held at the bank, checked, approved
5. report_settlement          → outcome: verified
6. get_receipt                → 2 KB, verifies offline