x402Shield PRIVATE BETA

Integrate x402Shield.

This page describes the public integration contract. Private beta participants receive endpoint access, credentials and environment-specific configuration separately.

Request / response

Send the payment intent and the exact request context it authorizes, before signing. x402Shield returns an authorization decision — never a signature.

  1. Send the payment intent and request context to x402Shield before signing.
  2. Receive AUTHORIZED, a policy denial, or REQUIRE_APPROVAL.
  3. Sign only after authorization is granted.
  4. Preserve the resulting authorization / evidence state for later reconciliation.
POST /enforce
{
  "request": {
    "method": "POST",
    "uri": "https://api.example.com/v1/resource",
    "host": "api.example.com",
    "body_sha256": "<sha256 of the exact request body being authorized>"
  },
  "requirement": {
    "network": "base",
    "asset": "usdc",
    "amount_micros": 3000000,
    "recipient": "0xmerchant",
    "scheme": "exact"
  },
  "agent_id": "your-agent-id",
  "session_id": "your-session-id",
  "idempotency_key": "unique-per-logical-request"
}

Decision semantics

Every request resolves to exactly one of three states.

ALLOW

HTTP 200. The payment is authorized. A reservation and grant fingerprint are returned for the signing step.

REQUIRE_APPROVAL

HTTP 202. The payment is parked pending explicit approval before it can be resumed and signed.

DENY

HTTP 403 (or 409/410 for replay/expiry-class denials). Not authorized. A reason code explains why.

200 AUTHORIZED
{
  "decision": "AUTHORIZED",
  "intent_id": "intent-...",
  "binding_digest": "0x...",
  "grant_fingerprint": "...",
  "reservation_id": "resv-...",
  "expires_at": 1798761600
}
202 approval_required
{
  "status": "approval_required",
  "approval_request_id": "appr-...",
  "intent_id": "intent-...",
  "approval_expires_at": 1798761600,
  "reason": "amount exceeds approval threshold"
}
403 DENY
{
  "error": {
    "code": "BUDGET_EXCEEDED",
    "message": "payment enforcement was denied by policy, budget, or binding verification",
    "requestId": "req_..."
  }
}

Reason codes

A non-exhaustive list of the reason codes a DENY decision can carry.

CodeMeaning
POLICY_DENIEDRecipient, network, asset or other policy rule not satisfied.
BUDGET_EXCEEDEDAmount would exceed the configured transaction, session or agent budget.
REPLAY_DETECTEDThis payment proof or authorization has already been used.
DUPLICATE_INTENTThis intent was already processed under a different idempotency key.
IDEMPOTENCY_KEY_CONFLICTThe same idempotency key was reused with a different request.
APPROVAL_EXPIREDThe approval window for a parked payment has elapsed.
APPROVAL_BINDING_MISMATCHSupplied approval evidence does not match the original request binding.

Integration flow

Agent forms intent→POST /enforce→AUTHORIZED / APPROVAL / DENY→Sign only if AUTHORIZED→Evidence recorded

Get integration access

Full endpoint access, environment scoping and credential issuance are provided to private beta participants.

Apply for Private Beta