Protection API Quickstart

Use the Cardinal Protection API to evaluate transaction intent before your wallet or application asks a user to sign.

The current Protection API is a professional MVP for sandbox integrations and controlled pilots. Your Cardinal onboarding contact will provide the appropriate API host and credentials. Do not use demo credentials in production.

Prerequisites

Before you begin, you need:

A Cardinal pilot API key
The API base URL supplied during onboarding
A transaction intent containing sender, recipient, chain, token, and amount

1. Configure your environment

Store the values supplied during onboarding as environment variables.

export CARDINAL_API_URL="https://<your-cardinal-api-host>"
export CARDINAL_API_KEY="<your-pilot-api-key>"

Never expose the API key in frontend code, browser storage, public repositories, or logs.

2. Check a transaction

Call the protection endpoint before requesting a wallet signature, token approval, or contract transaction.

curl -X POST "$CARDINAL_API_URL/api/check-transaction" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CARDINAL_API_KEY" \
  -d '{
    "from_address": "0x123",
    "to_address": "0x456",
    "chain": "arbitrum",
    "token": "USDC",
    "amount": 500,
    "transaction_type": "safe_send",
    "contract_verified": true,
    "permissions": []
  }'

The required request fields are:

Field	Type	Description
`from_address`	string	Sender wallet address
`to_address`	string	Recipient wallet address
`chain`	string	Chain slug
`token`	string	Token symbol
`amount`	number	Proposed transfer amount

3. Handle the decision

A successful check returns a stable decision shape.

{
  "request_id": "req_example",
  "risk_score": 18,
  "risk_level": "LOW",
  "network_valid": true,
  "warnings": [],
  "findings": [],
  "recommended_action": "ALLOW",
  "checked_at": "2026-08-02T10:00:00.000Z"
}

Decision	Application behaviour
`ALLOW`	Continue to the protected signature or contract flow
`REVIEW`	Show the findings and require explicit acknowledgement
`BLOCK`	Stop the protected flow

Treat risk_score as the summary, findings as the reasons, and recommended_action as the decision. Do not build application logic from the score alone.

4. Continue only after the check

The protected sequence is:

Compose transaction intent
→ POST /api/check-transaction
→ Display ALLOW, REVIEW, or BLOCK
→ Continue only for ALLOW or an explicitly acknowledged REVIEW
→ Stop for BLOCK

If the Protection API is unavailable, show a real error. A live integration must never silently fall back to mock data.

Explore the Protection API

Review the endpoint, response model, and current pilot limitations.

Getting Started

Products

Developers

Security

Resources

Protection API Quickstart

Prerequisites

1. Configure your environment

2. Check a transaction

3. Handle the decision

4. Continue only after the check

Explore the Protection API

​Prerequisites

​1. Configure your environment

​2. Check a transaction

​3. Handle the decision

​4. Continue only after the check

Explore the Protection API

Prerequisites

1. Configure your environment

2. Check a transaction

3. Handle the decision

4. Continue only after the check