Rails: card & crypto

The dual-rail model

An agent can transact over one of two rails today: card or crypto. The design principle is that the rail is a thin layer at the edges. Everything that makes Mandate Labs a trust layer — KYA scoring, mandate and authority enforcement, Verifiable Intent, decision-quality scoring, and the outcome feedback loop — is identical across rails. The rail only selects which transaction context applies and which risk adapter scores it.

card is the default, so every existing card payload is unchanged. crypto is opt-in and adds a rail-specific context block plus two pieces a card transaction doesn't need: a signed transaction-authorization attestation and a settlement watcher.

The card rail

The crypto rail

Enabling rails

Rails are enabled at the Program level. When a Program is provisioned it carries an enabled-rails list — by default ["card", "crypto"] — and a Principal enrolled in that Program can hold mandates on any enabled rail. A mandate that names a rail the Program (or environment) hasn't enabled is rejected, and an attempt to authorize over a disabled rail declines with RAIL_NOT_ENABLED.

Declaring rails on a mandate

A Mandate declares which rails the agent may use via the rails array — a subset of {"card", "crypto"} that must be non-empty. An agent can hold a single mandate covering both rails, or separate mandates per rail.

When "crypto" is in rails, a crypto block is required (omitting it is a validation error). The block bounds the on-chain surface the agent may touch:

The mandate's standard limits (max_amount_per_transaction, max_daily_amount, currency) still apply on either rail — the economic amount is enforced regardless of how the value moves.

How authorize differs

The same POST /authorize endpoint serves both rails; the rail discriminator selects what else the request must carry.

Card authorize

rail defaults to CARD. The request carries the card-world fields — amount, currency, mcc, merchant_id/merchant_name, country — plus the mandatory intent_context. The engine checks the mandate's MCC, country, amount, and velocity constraints, scores trust and intent, and returns APPROVE / STEP_UP / DECLINE. No crypto block is allowed on a card request.

Crypto authorize

Set rail: "CRYPTO" and include a crypto context block describing the on-chain transfer:

• chain & asset — the settlement chain and asset (e.g. base, USDC). For a known pair, the chain id, ERC-20 contract, and token decimals are resolved automatically (base → 8453, USDC → 6 decimals).
• counterparty — the destination address (the x402 payTo), screened by the crypto risk adapter.
• from_address — the payer/agent wallet, bound into the attestation as the EIP-3009 from.
• value & operation — the human-readable token amount (defaults to the request amount for a stablecoin transfer) and the on-chain operation (transfer by default; swap, contract_call, bridge are recognized so the adapter can weight them).

The engine runs the same trust + intent pipeline, additionally enforces the crypto mandate constraints (chain, asset, counterparty), and on APPROVE attaches an attestation object to the response: { jws, kid, nonce, valid_after, valid_before, expires_at }. EVM address formats are validated at the edge, so malformed input is rejected before it reaches the adapter.

Card vs crypto

Worked examples

Mandates are created with your Client API key; authorize calls use the Principal API key (see Authentication).

Card — mandate & authorize

curl -X POST https://api.mandatelabs.ai/api/v1/agents/agt_…/mandates \
  -H "X-API-Key: mdt_live_…" -H "Content-Type: application/json" \
  -d '{
    "rails": ["card"],
    "limits": {
      "max_amount_per_transaction": 500,
      "max_daily_amount": 2000,
      "currency": "USD"
    },
    "allowed_mccs": ["5812", "5814"],
    "allowed_countries": ["USA"]
  }'

curl -X POST https://api.mandatelabs.ai/api/v1/authorize \
  -H "X-API-Key: mdt_live_…" -H "Content-Type: application/json" \
  -d '{
    "rail": "CARD",
    "agent_id": "agt_…",
    "amount": 42.00,
    "currency": "USD",
    "mcc": "5812",
    "merchant_name": "Blue Bottle Coffee",
    "country": "USA",
    "intent_context": {
      "intent_type": "PURCHASE",
      "task_reference": "Team lunch — order from the cafe nearest the office"
    }
  }'
# → { "decision": "APPROVE", "reason_codes": [...], "kya_score": 0.87, ... }

Crypto — mandate & authorize

curl -X POST https://api.mandatelabs.ai/api/v1/agents/agt_…/mandates \
  -H "X-API-Key: mdt_live_…" -H "Content-Type: application/json" \
  -d '{
    "rails": ["crypto"],
    "limits": {
      "max_amount_per_transaction": 50,
      "max_daily_amount": 500,
      "currency": "USD"
    },
    "crypto": {
      "chains": ["base"],
      "assets": ["USDC"],
      "max_transfer": 25
    }
  }'

curl -X POST https://api.mandatelabs.ai/api/v1/authorize \
  -H "X-API-Key: mdt_live_…" -H "Content-Type: application/json" \
  -d '{
    "rail": "CRYPTO",
    "agent_id": "agt_…",
    "amount": 1.20,
    "currency": "USD",
    "crypto": {
      "chain": "base",
      "asset": "USDC",
      "counterparty": "0x1234abcd...ef01",
      "from_address": "0xabcd1234...5678",
      "operation": "transfer"
    },
    "intent_context": {
      "intent_type": "TRANSFER",
      "task_reference": "Pay per-call API fee for the pricing data request"
    }
  }'
# → APPROVE with a bound attestation the wallet verifies before signing:

{
  "decision": "APPROVE",
  "kya_score": 0.83,
  "attestation": {
    "jws": "eyJ…compact-JWS…",
    "kid": "a1b2c3d4e5f60718",
    "nonce": "0x…bytes32…",
    "valid_after": 1782561600,
    "valid_before": 1782561900,
    "expires_at": "2026-06-27T12:05:00Z"
  }
}

The wallet / AA module / x402 facilitator fetches the verification keys from GET /api/v1/crypto/attestations/jwks.json, verifies the JWS, and confirms the attestation binds this exact transfer (recipient, value, nonce, chain id, token, and — when present — the from address and time window). It signs and broadcasts the EIP-3009 transferWithAuthorization only on a match. Afterward it reports the broadcast tx to POST /api/v1/crypto/settlements, and the watcher records a SETTLED outcome once the transaction reaches the required confirmations on Base.

When to use each

• Use the card rail when the agent buys from ordinary merchants — anything that accepts a card, priced in fiat, where MCC/merchant/country controls and the card-scheme settlement and dispute machinery are what you want.
• Use the crypto rail for machine-to-machine, pay-per-call commerce — x402-style USDC micropayments to APIs and services on Base, where you want sub-cent-overhead settlement and a cryptographic authorization the payer's wallet can verify independently before it signs.
• Use both by giving the agent a mandate with rails: ["card", "crypto"] (and a crypto block), or separate per-rail mandates. The same agent, the same trust score, and the same intent model govern both — only the context and the evidence differ.

Next steps