AP2
MANDATES.

What is a Mandate?

Instead of giving an agent your private key — which would let it spend any amount, any time — you sign a mandate. A mandate is a policy document stored in P402 that the router enforces on every request the agent makes.

The mandate defines:

DID Format

Mandates use Decentralized Identifiers (DIDs) to identify both the user (grantor) and the agent (grantee). A DID is a string that uniquely identifies an entity without a central authority.

Auto-Provisioned Mandates (CDP Sessions)

The easiest way to use mandates. When you create a session with wallet_source: "cdp" and an agent_id, P402 automatically creates a payment mandate and links it to the session. Every auto-pay call through this session is enforced against the mandate — no separate API call needed.

curl -X POST https://p402.io/api/v2/sessions \
  -H "Authorization: Bearer $P402_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_source": "cdp",
    "agent_id": "my-research-agent",
    "budget_usd": 10.00,
    "expires_in_hours": 24
  }'

{
  "session_id": "ses_...",
  "budget_usd": 10.00,
  "expires_at": "2026-04-17T12:00:00.000Z",
  "policies": {
    "ap2_mandate_id": "mnd_abc123"   // Mandate auto-created and linked
  },
  "wallet": {
    "address": "0x...",
    "source": "cdp"
  }
}

Manual Mandate Creation

For non-CDP sessions or when you need custom constraints — like restricting to specific service categories or using a cryptographic key identity — create a mandate directly.

curl -X POST https://p402.io/api/a2a/mandates \
  -H "Authorization: Bearer $P402_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandate": {
      "type": "intent",
      "user_did": "did:p402:tenant:t_abc123",
      "agent_did": "did:p402:agent:my-research-agent",
      "constraints": {
        "max_amount_usd": 50.00,
        "allowed_categories": ["inference", "search", "data"],
        "valid_until": "2026-12-31T23:59:59Z"
      },
      "signature": "0x..."
    }
  }'

{
  "mandate_id": "mnd_xyz789",
  "status": "active",
  "type": "intent",
  "user_did": "did:p402:tenant:t_abc123",
  "agent_did": "did:p402:agent:my-research-agent",
  "constraints": {
    "max_amount_usd": 50.00,
    "allowed_categories": ["inference", "search", "data"],
    "valid_until": "2026-12-31T23:59:59Z"
  },
  "amount_spent_usd": 0.00,
  "created_at": "2026-04-16T12:00:00.000Z"
}

Allowed Categories

The allowed_categories constraint is an allowlist. If you omit it, the agent can spend in any category. If you include it, only the listed categories are permitted — any request categorized differently returns MANDATE_CATEGORY_DENIED.

Mandate Lifecycle

A mandate moves through these states. Status transitions are triggered automatically by the router — you don't need to update them manually.

Check mandate status

curl https://p402.io/api/a2a/mandates/mnd_xyz789 \
  -H "Authorization: Bearer $P402_API_KEY"

{
  "mandate_id": "mnd_xyz789",
  "status": "active",
  "type": "intent",
  "constraints": {
    "max_amount_usd": 50.00,
    "allowed_categories": ["inference", "search", "data"],
    "valid_until": "2026-12-31T23:59:59Z"
  },
  "amount_spent_usd": 12.34,    // How much the agent has spent so far
  "remaining_usd": 37.66,       // Budget remaining
  "created_at": "2026-04-16T12:00:00.000Z"
}

How Agents Request Spending

An agent doesn't call the mandates API directly. Instead, it includes its agent_did and the mandate_id in the session or request. P402 verifies the mandate before processing the request and deducts from the budget after settlement.

The verification order is:

Revoke a Mandate

Revocation is immediate and permanent. Any in-flight request using this mandate will be rejected. Use this if you lose trust in an agent or need to stop spending immediately.

curl -X DELETE https://p402.io/api/a2a/mandates/mnd_xyz789 \
  -H "Authorization: Bearer $P402_API_KEY"

# Response: 200 OK
{ "mandate_id": "mnd_xyz789", "status": "revoked" }

Error Codes