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

# Exchange Integration

> Protect exchange withdrawals and high-risk transfers before settlement with Cardinal's transaction decision layer.

Cardinal helps exchanges place an explainable decision point immediately before value moves. Submit the final withdrawal intent to the Protection API, apply your exchange policy to the returned `ALLOW`, `REVIEW`, or `BLOCK` decision, and route the transfer through the appropriate settlement path.

<Warning>
  Cardinal is pilot-ready, but this guide does not represent unrestricted production or mainnet approval. SafeSend is currently a connected Arbitrum Sepolia testnet MVP. Programmable Escrow remains in final testing and security hardening.
</Warning>

## Recommended architecture

Keep Cardinal behind your exchange backend. Never expose a partner API key in a browser or mobile client.

1. The customer confirms the recipient, network, asset, and amount.
2. Your withdrawal service completes authentication and internal policy checks.
3. A server-side Cardinal adapter submits the canonical transaction intent.
4. Your policy engine combines Cardinal's decision with account, velocity, destination, and operational controls.
5. The withdrawal is allowed, paused for review, routed to a protected settlement flow, or blocked.
6. Your exchange records the final transaction hash and settlement outcome.

<Card title="Decision point" icon="shield-check">
  Call Cardinal after the withdrawal intent is final, but before signing or broadcasting the transaction.
</Card>

## Submit the withdrawal intent

Use the Protection API endpoint documented in the [Protection API](/protection-api) reference:

```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": "0xExchangeHotWallet",
    "to": "0xCustomerDestination",
    "chain": "arbitrum",
    "token": "USDC",
    "amount": "2500",
    "transaction_type": "transfer"
  }'
```

Required fields are `from`, `to`, `chain`, `token`, and `amount`. Include `transaction_type`, `contract_address`, `contract_verified`, `approval_amount`, and `permissions` when they describe the proposed action.

Each request represents one transaction intent. Do not assume a public batch-withdrawal endpoint, webhook, or asynchronous callback unless it is included in your partner agreement.

## Map decisions into exchange policy

| Cardinal decision | Minimum exchange action                          | Typical next step                                                             |
| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| `ALLOW`           | Continue only if all exchange controls also pass | Sign and broadcast through the normal withdrawal path                         |
| `REVIEW`          | Pause automatic settlement                       | Show a clear warning, require acknowledgement, or send the case to operations |
| `BLOCK`           | Stop the withdrawal flow                         | Prevent signing and record the findings for investigation                     |

Your exchange may apply stricter controls than Cardinal. It must not weaken a `BLOCK` decision or silently convert an unavailable/error response into `ALLOW`.

## Re-check rules

Run a new Cardinal check whenever a material part of the intent changes, including:

* Recipient address
* Network or chain
* Token or amount
* Contract address
* Approval amount or permissions
* Settlement method

Define a partner-specific freshness window for queued withdrawals. If a decision expires before signing or broadcasting, re-submit the final intent.

## Protected settlement routes

A decision can inform more than a binary allow-or-block control:

* **Direct settlement:** use only when Cardinal and all exchange policies allow the withdrawal.
* **SafeSend:** route eligible pilot transfers through a delay or cancellation-window flow. The verified integration is currently on Arbitrum Sepolia testnet.
* **Programmable Escrow:** use for agreed pilot workflows that require release conditions, cancellation, or further approval. Escrow is not described as audited or unrestricted mainnet infrastructure.
* **Manual or multisig approval:** require an operator or additional signer before settlement.

The exact route remains an exchange policy decision. Contract addresses, fee configuration, supported production networks, and audit status must be confirmed in the partner implementation plan.

## Audit trail

Store enough information to reconstruct every decision:

* Exchange withdrawal ID and Cardinal `request_id`
* Canonical recipient, network, token, amount, and transaction type
* Cardinal decision and findings
* Exchange policy result and selected settlement route
* Customer acknowledgement or manual-review outcome
* Signing time, transaction hash, and final status
* Re-check history when the intent changed or expired

Avoid logging the API key, authentication secrets, full session tokens, or unnecessary customer data.

## Errors, timeouts, and rate limits

Treat protection as a control boundary:

* Use short, bounded timeouts and controlled retries.
* Apply exponential backoff to `429` responses.
* Do not retry validation or authentication failures without correcting the request.
* Queue or pause the withdrawal if Cardinal is unavailable.
* Never default to `ALLOW`, use mock data, or bypass the check silently.
* Alert operations when failures cross your agreed threshold.

## Current capability boundary

The current Protection API provides pre-transaction decisioning and deterministic risk checks for the submitted intent. Supported input slugs include `ethereum`, `bnb`, `polygon`, `base`, `arbitrum`, `optimism`, and `solana`; this does not by itself mean every chain has completed exchange production validation.

Incoming-funds analysis, source-of-funds tracing, illicit-exposure detection, sanctions screening, and one-to-two-hop exposure analysis are roadmap capabilities. Do not present the current integration as a complete AML, KYT, sanctions, or stolen-funds screening system.

Cardinal is designed as a transaction decision and protected-settlement layer. Your exchange remains responsible for authentication, custody controls, customer and jurisdictional requirements, case management, legal review, AML policy, and regulatory obligations.

## Pilot checklist

Before enabling a live exchange flow:

* Agree on the withdrawal types, assets, networks, and limits included in the pilot.
* Keep the API key in a secret manager and rotate it under an agreed procedure.
* Validate request and response schemas in a non-production environment.
* Test `ALLOW`, `REVIEW`, `BLOCK`, timeout, `429`, and unavailable-service paths.
* Confirm re-check and decision-expiry rules.
* Verify operator escalation and customer messaging.
* Reconcile Cardinal request IDs with withdrawal IDs and transaction hashes.
* Confirm SafeSend or Escrow contract addresses, audit status, fees, and network readiness separately.
* Complete exchange security, legal, AML, and jurisdiction-specific review.

## Next steps

Start with a narrow pre-withdrawal pilot: one network, a small asset set, explicit limits, and manual review for `REVIEW` decisions. Expand only after decision quality, latency, operational handling, and settlement reconciliation meet the agreed acceptance criteria.