API Reference

Introduction

CLEARAGENT is a single-call compliance layer that sits between an AI agent and a payment rail. Send a KYA credential token and transaction details; receive a verdict — PROCEED, REVIEW, BLOCK, or UNKNOWN — in under 50ms.

The API runs on Cloudflare Workers at the edge. There is no server, no backend, no warm-up time. Every request is processed in the data center closest to the caller.

Authentication

All endpoints except /v1/health and /v1/.well-known/jwks.json require a Bearer token in the Authorization header.

curl https://api.clearagent.dev/v1/screen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Contact [email protected] to request a credentialed API key.

Base URL

https://api.clearagent.dev

Verdict Reference

Every POST /v1/screen response includes a verdict field with one of four values:

Error Codes

Register Agent

Issue a W3C Verifiable Credential (ES256-signed JWT) for an AI agent. The operator wallet and legal name are OFAC-screened at issuance. The credential is valid for 91 days and stored in KV under cred:{agentId}.

Request body

spendPolicy object

Example request

curl -X POST https://api.clearagent.dev/v1/agents/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "PayrollBot v2",
    "agentFramework": "LangChain",
    "underlyingModel": "claude-sonnet-4-6",
    "agentType": "autonomous",
    "operatorLegalName": "Acme Corp",
    "operatorWallet": "0xYourWalletAddress",
    "purpose": "Automated USDC payroll disbursements to contractors",
    "spendPolicy": {
      "maxSingleTxUSDC": 10000,
      "dailyLimitUSDC": 50000,
      "allowedChains": ["ETH", "BASE"],
      "counterpartyScreening": "OFAC+CONS",
      "noMixerProtocols": true
    }
  }'

Example response

{
  "agentId": "agt_Xk9mQ2Rz",
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "credential": {
    "@context": ["https://www.w3.org/2018/credentials/v1", "https://kya.protocol/v1"],
    "type": ["VerifiableCredential", "KYAAgentCredential"],
    "issuer": "did:kya:clearagent-alpha",
    "credentialSubject": {
      "agentId": "agt_Xk9mQ2Rz",
      "agentName": "PayrollBot v2",
      "agentType": "autonomous",
      "operatorLegalName": "Acme Corp",
      "spendPolicy": { "maxSingleTxUSDC": 10000, "dailyLimitUSDC": 50000, "allowedChains": ["ETH","BASE"] },
      "complianceAttestation": {
        "ofacAtIssuance": "CLEAR",
        "screenedAt": "2026-03-11T14:22:00Z",
        "credentialStatus": "ACTIVE"
      }
    },
    "expirationDate": "2026-06-10T14:22:00Z"
  }
}

Screen Transaction

Screen a proposed transaction against the 25-rule compliance engine. Returns a verdict in under 50ms. A txnId is generated for every call and the full result is written to the tamper-evident audit log (90-day retention).

Request body

Example request

curl -X POST https://api.clearagent.dev/v1/screen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "amount": 4500,
    "chain": "ETH",
    "rail": "USDC",
    "cpWallet": "0xRecipientWalletAddress",
    "cpName": "Contractor LLC",
    "cpType": "business"
  }'

Example response — PROCEED

{
  "verdict": "PROCEED",
  "txnId": "txn_A8bKmQ3x",
  "rule": null,
  "reason": "All compliance checks passed.",
  "agentId": "agt_Xk9mQ2Rz",
  "agentName": "PayrollBot v2",
  "operatorLegalName": "Acme Corp",
  "credentialStatus": "ACTIVE",
  "ofacSource": "kv:live",
  "screenedAt": "2026-03-11T14:23:01Z",
  "latencyMs": 38
}

Example response — BLOCK (OFAC hit)

{
  "verdict": "BLOCK",
  "txnId": "txn_B7cNpR4y",
  "rule": "R6_COUNTERPARTY_WALLET_OFAC",
  "reason": "Counterparty wallet matches OFAC SDN list: Lazarus Group / DPRK (Ronin Bridge, $620M, Mar 2022)",
  "agentId": "agt_Xk9mQ2Rz",
  "screenedAt": "2026-03-11T14:23:44Z",
  "latencyMs": 29
}

25-Rule Screening Precedence

Rules are evaluated in order — first match wins. BLOCK rules take precedence over REVIEW rules.

Create Fleet

Create a fleet spend envelope under an operator. Agents can be assigned to a fleet, which enforces an aggregate daily spend limit across all agents in the fleet. Useful for organizations running multiple agents under a shared budget.

curl -X POST https://api.clearagent.dev/v1/fleets/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fleetName": "Finance Operations Fleet",
    "operatorLegalName": "Acme Corp",
    "dailyLimitUSDC": 200000
  }'

Create Delegate

Mint a child agent credential from a parent agent credential. The child credential inherits the parent's policy and can only narrow it — it cannot expand spend limits or add chains beyond what the parent allows. Delegation depth is capped at 3 levels.

Register User

Issue a 30-day individual user credential. Valid for supervised agent contexts only — autonomous agents cannot be assigned user credentials. User credentials are stored under user:{userId} in KV with a 31-day TTL.

Human Attestation

Record a human heartbeat re-attestation for an autonomous agent. Autonomous agents must be re-attested every 24 hours. If attestation is stale, transactions over $10,000 are automatically escalated to REVIEW. Attestation records are stored under attest:{agentId} with a 25-hour TTL.

curl -X POST https://api.clearagent.dev/v1/agents/agt_Xk9mQ2Rz/attest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attestedBy": "[email protected]",
    "note": "Routine daily attestation"
  }'

Review Disposition

Post a BSA officer's disposition on a transaction that received a REVIEW verdict. This is the human-in-the-loop endpoint: when the screening engine flags a transaction for review (spend policy, velocity anomaly, model change, etc.), a compliance officer calls this endpoint to record their decision.

Path Parameters

Request Body

Example Request

curl -X POST https://api.clearagent.dev/v1/reviews/txn_a1b2c3d4 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "disposition": "APPROVED",
    "reviewedBy": "J. Smith, BSA Officer",
    "notes": "Reviewed velocity flag — within normal operating pattern for this agent."
  }'

Response (200)

Returns the full updated audit record with disposition fields appended:

{
  "txnId": "txn_a1b2c3d4",
  "verdict": "REVIEW",
  "ruleTriggered": "VELOCITY_SPIKE",
  "reason": "Transaction velocity exceeded 3x rolling average",
  "disposition": "APPROVED",
  "reviewedBy": "J. Smith, BSA Officer",
  "reviewedAt": "2026-03-15T14:22:01Z",
  "notes": "Reviewed velocity flag — within normal operating pattern for this agent.",
  "sarEscalated": false,
  ...
}

Dispositions

Error Responses

Get Audit Record

Retrieve a tamper-evident audit record by its txnId. Every /v1/screen call generates a txnId (format: txn_XXXXXXXX) and writes the full result plus request inputs to KV. Records are retained for 90 days.

curl https://api.clearagent.dev/v1/audit/txn_A8bKmQ3x \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "txnId": "txn_A8bKmQ3x",
  "verdict": "PROCEED",
  "rule": null,
  "reason": "All compliance checks passed.",
  "agentId": "agt_Xk9mQ2Rz",
  "agentName": "PayrollBot v2",
  "operatorLegalName": "Acme Corp",
  "credentialStatus": "ACTIVE",
  "ofacSource": "kv:live",
  "screenedAt": "2026-03-11T14:23:01Z",
  "_request": {
    "amount": 4500,
    "chain": "ETH",
    "cpWallet": "0xRecipient...",
    "cpName": "Contractor LLC",
    "rail": "USDC"
  }
}

Health Check

Returns API version, OFAC list status, KV connectivity, and signing key state. No authentication required.

curl https://api.clearagent.dev/v1/health

{
  "status": "ok",
  "version": "0.2.0",
  "ofac": {
    "source": "kv:live",
    "count": 77,
    "syncedAt": "2026-03-11T02:00:14Z"
  },
  "kv": "connected",
  "signingKey": "production"
}

JWKS Public Key

Returns the P-256 public key in standard JWKS format. Use this endpoint to independently verify any KYA credential JWT without calling the CLEARAGENT API — any standard JWT library that supports ES256 can verify the signature.

curl https://api.clearagent.dev/v1/.well-known/jwks.json

{
  "keys": [{
    "kty": "EC",
    "crv": "P-256",
    "use": "sig",
    "alg": "ES256",
    "kid": "cc-v1",
    "x": "...",
    "y": "..."
  }]
}