> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cardinalweb3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Protection API Quickstart

> Run your first Cardinal transaction risk check.

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

<Warning title="Controlled pilot">
  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.
</Warning>

## 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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```json theme={"dark"}
{
  "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                                |

<Info>
  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.
</Info>

## 4. Continue only after the check

The protected sequence is:

```text theme={"dark"}
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.

<Card title="Explore the Protection API" icon="shield-check" href="/protection-api">
  Review the endpoint, response model, and current pilot limitations.
</Card>