X402 Secure Operations Runbook

This runbook covers the partner-ready operating model for X402 Secure when it processes Verifiable Intent-style evidence, AP2 mandate context, x402 payment binding, and Trustline risk decisions.

Ownership

Runtime Modes

Issuer Key Rotation

1. Add the new issuer key or JWKS entry to Trustline configuration.
2. Keep the old key active for the overlap window agreed with the issuer.
3. Run VI verification tests for:
   • current key
   • rotated key
   • expired key
   • unknown issuer
4. Confirm X402 Secure still receives vi.verified=true only when Trustline verification succeeds.
5. Remove the old key only after all active VI presentations signed by the old key have expired.

Rollback:

• Restore the previous Trustline issuer config.
• Set policy requireVerifiedIntent=false only for sandbox or controlled partner demos.
• Keep requireVerifiableIntent=true if the flow still requires evidence presence.

Trustline Outage

Default production posture should be fail-closed for flows that require VI/AP2 risk enforcement.

Do not bypass Trustline from the XRPL x402 Facilitator. If Trustline is down, the Facilitator should receive a X402 Secure decision or controlled error, not call Trustline directly.

Review Mode

reviewMode controls how X402 Secure treats Trustline review decisions:

Acceptance check:

• A review decision with reviewMode=block must not call the upstream facilitator.
• Dashboard fields must preserve the review reasons and warning list.

Receipt Retry and Idempotency

Settlement callbacks should include:

{
  "decisionId": "dec_123",
  "evidenceRef": "tl_evd_123",
  "settlementAttemptId": "settle_attempt_001",
  "idempotencyKey": "xrpl:dec_123:settle_attempt_001",
  "payment": {
    "network": "xrpl-mainnet",
    "transactionHash": "ABC123",
    "status": "settled"
  }
}

Rules:

• Retry receipt callbacks on transient X402 Secure or Trustline failures.
• Use a stable idempotencyKey for retries of the same settlement attempt.
• Use a new settlementAttemptId when the payment rail attempts settlement again.
• Failed attempts may have transactionHash=null; do not use transaction hash as the only idempotency key.

Evidence Retention and Privacy

Retain enough metadata for audit and disputes while minimizing sensitive VI claims:

• Store evidence refs, fingerprints, decision ids, policy, binding status, violation codes, and receipt ids.
• Avoid logging full VI presentations or raw disclosed claims unless explicitly required in a controlled audit environment.
• Redact authorization headers, bearer tokens, private keys, and full payment payloads in application logs.
• Keep partner-facing errors useful but narrow: expose violation codes and summary fields, not private credential contents.

XRPL Facilitator Validation

Before partner handoff, validate these XRPL items with the Facilitator team:

Monitoring

Track:

• Trustline decision latency and error rate.
• X402 Secure allow, deny, review, and unavailable counts.
• VI parse failures and verification failures.
• AP2 mandate missing or mismatch rates.
• Payment binding violation codes.
• Upstream facilitator calls blocked before settlement.
• Receipt callback success, retry, duplicate, and failure counts.

Alert when:

• Required VI flows suddenly allow without evidence.
• Deny or review rates spike for a partner.
• Trustline unavailable errors exceed the partner threshold.
• Receipt callback failures persist beyond the retry window.

Incident Response

1. Identify scope: paid API, proxy gateway, XRPL internal facilitator, or Trustline backend.
2. Preserve decision ids, evidence refs, trace ids, and receipt attempt ids.
3. Confirm whether settlement was attempted.
4. If settlement was not attempted, keep the payment blocked until policy is reviewed.
5. If settlement was attempted, reconcile receipt status and transaction hash with the payment rail.
6. Update partner with decision id and high-level violation codes only.

Release Checklist