x402 integration

The Citehouse Gateway is x402-compatible. Agents that hold a Stripe Link Wallet, a Coinbase Commerce wallet, or any x402-signatory wallet can pay per call without a pre-issued API key. The handshake is two HTTP round trips.

The handshake

1. Agent       → Gateway   POST /api/v1/corpora/asme/query
                            (no payment header)

2. Gateway     → Agent     402 Payment Required
                            X-Payment-Required: <settlement-quote>

3. Agent       → Wallet    sign(quote)
   Wallet      → Agent     settlement-token

4. Agent       → Gateway   POST /api/v1/corpora/asme/query
                            X-Payment-Settlement: <settlement-token>

5. Gateway     → Agent     200 OK
                            { passages: [...], ledger_entry_id, ... }

The settlement quote in step 2 contains the per-call rate, the customer scope, the ledger entry shape, and an expiry. It is signed by Citehouse and verifiable against the x402 Foundation's published key set.

Sample request and response

Initial call

POST /api/v1/corpora/asme/query HTTP/1.1
Host: api.citehouse.com
Content-Type: application/json

{
  "question": "Minimum wall thickness for B31.3 process piping?",
  "max_tokens": 1200
}

Gateway response

HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Payment-Required: 1

{
  "quote": {
    "ledger_entry_id_preview": "le_01JG9...",
    "rate_per_1k_tokens_usd": "0.30",
    "max_tokens": 1200,
    "max_charge_usd": "0.36",
    "expires_at": "2026-04-30T19:42:00Z",
    "settlement_endpoints": [
      "stripe:link-wallet",
      "x402:eip3009",
      "coinbase:commerce"
    ],
    "signature": "sig_v1_..."
  }
}

Retry with settlement

POST /api/v1/corpora/asme/query HTTP/1.1
Host: api.citehouse.com
Content-Type: application/json
X-Payment-Settlement: tok_v1_...

{
  "question": "Minimum wall thickness for B31.3 process piping?",
  "max_tokens": 1200
}

Successful response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "passages": [...],
  "tokens_returned": 482,
  "ledger_entry_id": "le_01JG9...",
  "settlement_status": "captured"
}

Wallet support matrix

| Wallet | Status | Notes | | --- | --- | --- | | Stripe Link Wallet for agents | Supported | Recommended path for production | | Coinbase Commerce | Supported | Settlement in USDC | | Generic EIP-3009 wallets | Supported | Verified against x402 Foundation key set | | Custom enterprise wallet | Available | Contact Citehouse |

Reconciliation

Each settlement token resolves to a single ledger entry on Citehouse's books. The ledger_entry_id returned in the success response cross-references your monthly invoice and your wallet's outbound payment history.

For audit, GET /api/v1/calls/:id returns the full ledger entry: timestamp, customer, society, standard, tokens returned, settlement token hash, and rate.