x402 API Developer Guide

Current Implementation Status

The API described here is complete for simulated x402 payments, policy evaluation, immutable event recording, merchant visibility, reconciliation, CSV ingestion, and audit exports. The dashboard and prototype still use DeterministicLocalFacilitator. It makes no network calls and moves no money. A Coinbase CDP live adapter is implemented behind the provider-neutral interface, but it is not registered with the gateway or enabled by default.

Coinbase CDP Facilitator Adapter

Zahlen's first real-provider adapter uses Coinbase CDP's hosted x402 facilitator. It sends the standard x402 version 2 payment envelope to the provider for verification and settlement. The rest of Zahlen continues to use the same provider-neutral records, policy decisions, reconciliation, and audit evidence.

Runtime configuration

Install the optional x402-live package group and load the following values from the approved deployment secret manager. Never place these values in code, CSV files, URLs, logs, screenshots, dashboard fields, or audit records.

Provider authentication, rate limits, rejected requests, timeouts, outages, and invalid responses become short deterministic reason codes. Raw provider response bodies and credential values do not cross the adapter boundary. Zahlen withholds the resource when verification or settlement cannot be trusted.

Environments and Feature Flags

Prototype flag

ZAHLEN_X402_PROTOTYPE_ENABLED=true enables routes under /v1/x402/prototype. Use this only in an approved local or test environment. When it is absent or false, prototype routes fail closed with HTTP 404.

Live-payment flag

ZAHLEN_X402_LIVE_PAYMENTS_ENABLED=true is one part of the future live-adapter gate. The flag alone cannot create live support. A registered live adapter, capability match, operational approval, and production-readiness evidence are also required.

Authentication and Merchant Scope

The x402 surfaces use three authentication patterns.

Merchant API-key header

The API key is resolved to one merchant and tenant. The merchant_id in the URL must match that identity. A mismatch returns HTTP 403. Missing, malformed, unknown, inactive, or revoked keys return HTTP 401.

x402 Protocol Headers

Encoding

Protocol headers contain standard Base64 text created from UTF-8 JSON. The decoded JSON limit is 16,384 bytes. Invalid Base64, oversized content, or a payload that fails x402 v2 validation returns HTTP 400.

Payment challenge shape

Payment payload shape

The accepted object must exactly match one challenge option. A nonce or proof must never be reused. Live provider payloads will be documented with their adapter when a live adapter is connected and approved.

Endpoint Summary

Protocol and merchant API routes

Protected Resource Lifecycle

1. Request the resource

When no payment proof is present, the response is HTTP 402. Its JSON body reports payment_required, deterministic test mode, and no monetary value. Decode the PAYMENT-REQUIRED response header to read the x402 v2 challenge.

2. Build and submit the proof

3. Interpret the result

• HTTP 200: verification, policy, and test settlement succeeded; the resource body is returned with PAYMENT-RESPONSE.
• HTTP 402 payment_denied: proof or policy failed and delivery was withheld.
• HTTP 402 payment_review_required: the policy requires human or approved follow-up before delivery.

Observability Timeline

The response contains the complete ordered record history for the correlation ID.

A denied, failed, or replayed lifecycle can contain a different number of records because settlement or release may not occur.

Append a Reconciliation Assessment

A successful request returns HTTP 201 with a new reconciliation record. Earlier records stay unchanged. Repeating the assessment creates new evidence rather than overwriting the original result.

Versioned Policy Profiles

Policy profiles are append-only. Post a new policy version instead of editing an existing row. Zahlen assigns contract_version, profile_id, tenant_id, and merchant_id; clients must not send those fields.

Create a policy

Amounts are strings containing non-negative atomic units, not floating-point numbers. Required lists cannot be empty or contain duplicates. The review threshold must be lower than the deny threshold.

Read the effective policy

The response is {"profile": {...}}. HTTP 404 means no policy is currently effective for that merchant.

Merchant Visibility APIs

Dashboard visibility

The response contains:

• scope and selected time-window information.
• summary counts and settled amounts by asset.
• transactions with payment, policy, settlement, delivery, and reconciliation states.
• identities for agent and wallet history.
• policyDecisions with reason codes and anomaly scores.
• anomaliesAndReplays for unusual or repeated activity.
• settlementAndDelivery and reconciliationExceptions.
• trends with time buckets and attempts per hour.
• dataQuality showing immutable x402 ledgers as the source.

Identity history

Supply agent_id, wallet_address, or both. Omitting both returns HTTP 422. The maximum activity window is 720 hours and the maximum limit is 500.

Downloadable Audit Evidence

The response is an application/zip download with these headers:

• Cache-Control: no-store
• X-Zahlen-Evidence-Fingerprint
• X-Zahlen-Evidence-Record-Count
• Content-Disposition with the generated filename

The ZIP contains:

Operator Dashboard APIs

These routes support the Zahlen browser dashboard. They use an authenticated browser session and tenant security context. They are not replacements for merchant-key API integration.

CSV preview

CSV commit

Submit the same file and merchant scope, plus the exact 71-character expected_fingerprint returned by preview. A changed file returns HTTP 409 and must be previewed again.

Canonical Schema and Data Rules

Zahlen records lifecycle evidence using contract version 1.0. Every record answers who attempted to pay, what they requested, under which authorization, what happened, whether it was expected, and what should happen next.

Canonical record types

• payment_resource_request
• http_402_challenge
• payment_authorization_proof
• verification_result
• policy_decision
• settlement_result
• resource_delivery_result
• replay_duplicate_attempt
• reconciliation_record

HTTP Status and Error Guide

Facilitator failures are normalized into safe reason codes such as facilitator_verify_timeout and facilitator_settle_timeout. Delivery is withheld when verification or settlement cannot be trusted.

Security Requirements

• Use HTTPS for all non-local requests.
• Never send or store private keys, seed phrases, mnemonics, signing secrets, passwords, bearer tokens, or unrelated credentials in x402 payloads.
• Treat wallet addresses, public transaction identifiers, public signatures, and agent IDs as identities and audit data.
• Keep merchant API keys server-side and rotate or revoke them under your normal access policy.
• Never reuse a nonce or payment proof.
• Do not release a resource based only on the presence of a proof; require verification and the policy result.
• Respect Review as a hold state, not an approval.
• Use correlation IDs rather than payment secrets when requesting support.
• Retain audit ZIPs according to your organization's evidence and privacy rules.

Integration Checklist

1. Use a local or approved development environment with the prototype flag enabled.
2. Create or select an active merchant and obtain a merchant-scoped API key.
3. Request weather-current and decode the PAYMENT-REQUIRED header.
4. Build a unique deterministic test proof using the exact accepted terms.
5. Submit the proof and confirm HTTP 200 plus PAYMENT-RESPONSE.
6. Read the correlation timeline and confirm expected record types.
7. Post and read a versioned policy profile.
8. Test Allow, Deny, Review, invalid proof, replay, timeout, and unavailable-facilitator paths.
9. Review visibility, identity history, reconciliation exceptions, and trends.
10. Download an audit bundle and verify its manifest fingerprint.
11. Confirm that card-payment regression tests and x402 tests remain green.
12. Keep live payments disabled until the Coinbase adapter, merchant terms, credentials, and rollout evidence pass the separate production-hardening review.