Cardinal
Cardinal Protection API

Best viewed on desktop

The Protection API reference is built for wide screens — code samples, payload tables, and the live Swagger console. Open this page on a desktop browser for the full documentation.

Back to home

cardinal://protect · api reference

Cardinal Protection API/pre-sign decisioning

Check risk before signature.

Call one endpoint with transaction details. Use the returned action: ALLOW, REVIEW, or BLOCK.

Try SafeSend flow →Read endpoint
01
transaction intent
02
risk engine
03
recommended action
04
wallet gate
01

Endpoint

Use the backend endpoint from trusted server environments. The MVP uses a Next.js proxy route so partner keys never touch the browser.

Backend
POST/api/check-transaction
MVP proxy
POST/api/protection/check
Auth header
x-api-key

Store this key server-side. For web products, call your own backend or the built-in Next proxy.

Request
Cardinal API
curl -X POST http://localhost:3001/api/check-transaction \
  -H "Content-Type: application/json" \
  -H "x-api-key: cardinal_demo_key" \
  -d '{
    "from_address": "0x1230000000000000000000000000000000000456",
    "to_address": "0x0000000000000000000000000000000000000001",
    "chain": "ethereum",
    "token": "USDC",
    "amount": 2500,
    "transaction_type": "safe_send",
    "contract_verified": true,
    "permissions": []
  }'
02

Verdict

Do not build product behavior from the score alone. Use recommended_action as the gate and use findings to explain the decision.

01
ALLOW
Low risk. Let the user proceed.
Continue
02
REVIEW
Something needs a human check before signing.
Warn clearly
03
BLOCK
Do not let funds leave the wallet.
Stop signing
Integration rule

`risk_score` helps explain confidence. `recommended_action` decides whether the app continues, warns, or blocks before signature.

Response
Cardinal API
{
  "request_id": "req_8b2a...",
  "risk_score": 18,
  "risk_level": "LOW",
  "network_valid": true,
  "warnings": [],
  "findings": [],
  "recommended_action": "ALLOW",
  "checked_at": "2026-06-22T06:50:00.000Z"
}
03

Payload

The request should be boring and explicit. Cardinal turns these transaction facts into explainable risk findings.

from_address
Who is sending value.
to_address
Who or what receives value.
chain
Where the transaction will execute.
token
The asset being moved.
amount
How much value is at risk.
transaction_type
The product flow, for example safe_send or escrow.
contract_verified
Whether the target contract source is verified.
permissions
Approval or contract permissions to inspect.
04

Run local

Run the backend first, then run the web MVP. Live mode shows a real API error if the backend is offline.

Backend

Starts Postgres, applies migrations, seeds demo key, then serves Swagger at `localhost:3001/docs`.

Web

Starts the MVP at `localhost:3004` and calls `/api/protection/check`.

Commands
Cardinal API
# Terminal 1: backend
cd cardinal-protection-api-be
docker compose up -d
npm run prisma:deploy
npm run prisma:seed
npm run start:dev

# Terminal 2: web MVP
cd cardinal-security-wallet/apps/web-modified-app/cardinal-protocol
npm run dev