Integrate14
HTTP API
Two endpoints are paid, everything else is free and public; there are no API keys. Paid calls are settled per request over x402 with Circle's facilitator on Arc. Internal ticks are protected by a bearer secret and are listed so you can run them yourself.
Endpoints
| Method | Path | Price | What it does |
|---|---|---|---|
POST | /api/v1/screen | 0.01 USDC | Full grade of one address (+ name, amountUsdc, payeeBook, clientId, depth). Verdict + signed attestation. Header X-CompliR-Decision-Id. Same-origin browser calls are free. |
POST | /api/v1/watch | 0.05 USDC / 30 d | Register address + webhookUrl (+ clientId, payeeBook). Adaptive re-screening; tier.changed webhooks. Header X-CompliR-Watch-Id. Settled after the handler succeeds. |
POST | /api/v1/tips | 0.05 USDC stake | Submit a staked tip about an address. Settled first; same-origin creates a demo tip. |
POST | /api/v1/shadow | free | Payee book + recent payments → wouldHold / wouldLimit / lookalikes / paymentsAtRisk. ≤ 50 addresses, 4 in flight, depth 1. |
GET | /api/v1/attestation/:address | free | Latest stored verdict + attestation (source: store); screens once if never seen (source: fresh). |
GET | /api/v1/badge/:address.svg | free | Screened-by-CompliR SVG from the store; grey unknown / expired; Cache-Control max-age=60. |
GET | /api/v1/decision/:id | free | One replayable decision-log entry: payload, prevHash, hash, anchorTx. |
GET | /api/v1/ledger?limit=50 | free | Most recent ledger entries, newest first. |
GET | /api/v1/ledger/verify | free | Re-walks the hash chain; { ok, brokenAt, length }. |
GET | /api/v1/network/:address | free | Anonymised network signal: heldElsewhere, concentrationHint, recent blocklist events. |
GET | /api/v1/network/events?limit=50 | free | Last USDC blocklist events the reactor saw and what it did. |
GET | /api/v1/map?limit=150 | free | Trust Map snapshot: nodes, edges, header stats; cached 10 s. |
GET | /api/v1/map/changes?limit= | free | Recent tier changes from the Trust Map tailer (≤ 200). |
GET | /api/v1/map/:address | free | One Trust Map node with its edges. |
GET | /api/v1/feed?limit=25 | free | Anonymised recent screenings (masked addresses). |
GET | /api/v1/numbers | free | Public counters; own wallets and internal client ids excluded. |
GET | /api/v1/company | free | Company snapshot + last ten operator decisions; cached 30 s. |
GET | /api/v1/payouts | free | Invoices, totals, mode, policy and missingForLive. POST adds a demo invoice (same-origin only). |
GET | /api/v1/report | free | Latest signed daily report (+ archive); ?format=md. /api/v1/report/:date[.md] for one day; 404 until the first report. |
GET | /api/v1/tips · /api/v1/tips/:id | free | Tip market totals, leaderboard, items (anonymised) · one tip. |
GET | /api/v1/edd/:id | free | Public view of an EDD request: questions, status, re-screen outcome. Never the answers. |
POST | /api/v1/edd/:id/answer | free | The counterparty answers once; answers stored privately, keccak logged, subject re-screened. Second submission → 409. |
GET | /api/v1/health | free | Liveness, chain id, explorer URL, USDC and registry addresses, x402 prices, signer mode, example addresses (real wallets). |
Prices are the operator's current prices (bounds), read per request; /api/v1/health reports the config defaults. With X402_DISABLED=1 (this deployment today) every endpoint is free and responses carry X-CompliR-Payment: disabled.
Internal ticks
POST|GET /api/internal/<worker> with Authorization: Bearer $CRON_SECRET runs one tick and returns its summary. Vercel crons call these (see Self-hosting); the worker/*.ts loops call the same functions.
- watcher
- due re-screens + webhooks + anchor-if-due
- trustmap
- tail Arc, grade recipients ≥ 25 USDC
- treasury
- guarded payouts tick
- operator
- one operator decision
- events
- blocklist reactor tick · POST { simulate } = drill
- refunds
- process the refund queue · POST manual refund / requeue
- tips
- verify + pay tips · POST { review, decision } human override
- usyc
- revenue yield tick: Circle Earn vault sweep (dry-run unless YIELD_MODE=live; YIELD_BACKEND=usyc for the legacy USYC Teller)
- report
- generate + sign a daily report (?date=, &force=1)
- circle
- Circle wallet status · POST { provision: true }
Error shape
json
{ "error": { "code": "VALIDATION_ERROR", "message": "…", "details": { … } } }
INVALID_JSON 400 · VALIDATION_ERROR 400 · NOT_FOUND 404 · NOT_IMPLEMENTED 501 · SERVICE_PAUSED 503 · INTERNAL_ERROR 500
x402: PAYMENT_MISCONFIGURED 503 · PAYMENT_VERIFY_UNAVAILABLE 502 · PAYMENT_SETTLE_UNAVAILABLE 502 · PAID_BUT_UNDELIVERED 502
Every response carries X-CompliR-Version: v1 and Cache-Control: no-store (badge, map and company set their own max-age).x402 headers and statuses
| Header | Direction | Meaning |
|---|---|---|
PAYMENT-REQUIRED | response (402) | base64 PaymentRequired: { x402Version: 2, error?, resource, accepts: [requirements] }; the same object is the JSON body |
PAYMENT-SIGNATURE | request | base64 PaymentPayload: { x402Version: 2, resource, accepted, payload: { signature, authorization } }. X-PAYMENT is accepted as a v1-named alias (payload must still be v2). |
PAYMENT-RESPONSE | response | base64 settle receipt: { success, transaction, network, payer, amount, errorReason? }. Mirrored as X-PAYMENT-RESPONSE. |
X-CompliR-Payment | response | CompliR's one-word state: disabled · required · settled · replay · retry · pending · settle-failed · verify-unavailable · settle-unavailable · not-charged · refund-queued |
| Status | X-CompliR-Payment | When |
|---|---|---|
| 402 | required | no PAYMENT-SIGNATURE, bad payload, wrong x402Version, requirements mismatch (scheme, network, asset, payTo, amount, validity), or facilitator /verify said invalid |
| 402 | pending | settlement_pending after status polls; retry with the SAME signed authorization to converge on the one payment |
| 402 | settle-failed | facilitator reported a failed settlement; not charged |
| 200 | settled | paid and delivered; receipt in PAYMENT-RESPONSE |
| 200 | replay | same nonce within 5 min after a settled payment: cached response, no second settle |
| 200 | retry | same nonce while the first attempt is still in flight |
| 4xx | not-charged | the handler refused (validation, paused) before settlement |
| 500 | not-charged | handler threw before settlement |
| 502 | verify-unavailable | facilitator /verify unreachable; no charge |
| 502 | settle-unavailable | facilitator /settle unreachable after the handler ran; retry with the same authorization, you will not be charged twice |
| 502 | refund-queued | settled but undelivered: PAID_BUT_UNDELIVERED, refund queued to the payer |
| 503 | - | PAYMENT_MISCONFIGURED: x402 enabled but X402_PAY_TO / facilitator URL missing; no charge |
Full flow, requirements and the facilitator in x402 payments.