Everything you need to integrate xFunnel's x402 bridge — architecture overview, live demo, API playground, and common integration questions.
xFunnel sits between your application and the x402 upstream relay. It accepts binary HTTP/S payment requests, verifies them via Coinbase CDP, captures its bridge fee, and forwards the payload to the upstream target. Every transaction is logged and metrics are exposed for intelligent routing.
A payment payload is sent to /api/v1/bridge with
Authorization: Pay address@chain, a SHA-256 request hash,
and Content-Type: application/octet-stream.
The bridge extracts the pay recipient, chain, fee percent, and request hash. It checks for duplicate requests using the request hash as an idempotency key to prevent double-processing.
For non-synthetic addresses (anything other than 0x1111...1111),
xFunnel calls the Coinbase Commerce API to verify the payment intent.
Synthetic addresses are auto-verified in test mode.
On successful verification, xFunnel collects the configured fee percentage
(default 5%, configurable 0–20%) and records it against the transaction.
The fee is settled to the configured CDP_SETTLEMENT_WALLET on ETH/Base.
The binary payload is forwarded to the x402 upstream relay
(signallayer-4.polsia.app by default, configurable via
X-Forward-To). The upstream response is returned to your app.
Every transaction writes to bridge_metrics (latency, upstream
status, error counts) and bridge_tx_logs (from/to, amount,
fee, status, latency per stage). Real-time KPIs available at
GET /api/v1/metrics.
0x1111 (synthetic addresses)
are auto-verified without calling Coinbase CDP — enabling integration testing
without real money. The rest of the flow (logging, fee capture, upstream routing)
runs identically.
| Component | Role | Config / Env |
|---|---|---|
/api/v1/bridge |
Primary x402 gateway endpoint. Accepts payment payloads, verifies, captures fees, routes upstream. | — |
/api/v1/metrics |
Live KPI panel: latency percentiles, uptime, fees collected, chain breakdown. | — |
/api/v1/bridge/status |
Upstream health probe: is signallayer reachable? Circuit-breaker status. | — |
| Coinbase CDP API | Payment verification for non-synthetic addresses. | COINBASE_CDP_API_KEY |
| Settlement wallet | Where bridge fees accumulate (ETH on Base). | CDP_SETTLEMENT_WALLET |
| bridge_metrics | Per-request latency and upstream health. | Auto-populated |
| bridge_tx_logs | Full transaction audit trail with fee and status. | Auto-populated |
| Chain | Fee Asset | Upstream Target | Status |
|---|---|---|---|
base |
ETH | signallayer-4.polsia.app (default) | Active |
solana |
SOL | signallayer-4.polsia.app | Active |
polygon |
MATIC | signallayer-4.polsia.app | Active |
This fires a real request against the bridge. Synthetic addresses
(0x1111...1111) are auto-verified without calling Coinbase CDP —
the full flow (logging, fee capture, upstream routing) runs as-is.
POST /api/v1/bridge with:
0x1111111111111111111111111111111111111111@base
application/octet-stream
sha256_demo_test_payload
5
demo x402 binary payload (32 bytes)
/api/v1/bridge. xFunnel verifies the
synthetic address, captures a 5% bridge fee, routes the payload upstream, and
returns the response with X-Funnel-Fee and X-Funnel-Tx-Hash
headers. Each demo fire writes a row to bridge_tx_logs and
bridge_metrics.
X-Funnel-Fee: 0.001 ETH
X-Funnel-Tx-Hash: 0x...
X-Funnel-Bridge-Version: 1.0.1
{
"status": "verified",
"upstream_tx_hash": "0x...",
"fee_captured": "0.001",
"fee_asset": "ETH",
"fee_chain": "base",
"latency_ms": 340
}Craft and fire x402 requests against the bridge. Leave fields at their defaults to send a minimal valid request. Synthetic addresses are auto-verified.
X-Funnel-Fee (ETH fee captured),
X-Funnel-Tx-Hash (settlement reference), and
X-Funnel-Bridge-Version in the response headers. These are
present on all 2xx responses.
POST /api/v1/bridge is the payment gateway — it accepts x402 binary payloads,
verifies via Coinbase CDP, captures fees, and routes to the upstream relay.
GET /api/v1/metrics is a read-only KPI endpoint that returns live stats
(latency percentiles, uptime, fees collected, chain breakdown). Your routing logic
calls metrics before deciding whether to route through the bridge.
402 Payment Required response means CDP couldn't verify the payment.
Inspect the WWW-Authenticate response header for the specific challenge.
Common causes: payment not yet confirmed on-chain, insufficient funds, or address
mismatch. Retry after the condition is resolved. No bridge fee is captured on 402.
503 Service Unavailable and sets a
Retry-After header with a backoff suggestion. Implement exponential
backoff in your retry logic. Use GET /api/v1/bridge/status to check
circuit-breaker status before making requests. Check GET /api/v1/metrics
to see upstream health (handshake_reliability, uptime_pct) and failover decisions.
No fee is captured when the bridge returns 503.
transaction_amount × (fee_percent / 100). Default is 5%.
Override per-request with the X-Bridge-Fee-Percent header (range 0–20).
Fees are captured in ETH on Base and settled to the configured
CDP_SETTLEMENT_WALLET. Fee capture is atomic with the 200 response —
if the bridge returns 200, the fee was captured. If it returns 402, 503, or an
error, no fee was captured.
X-Forward-To header to any HTTPS endpoint that accepts
x402 binary payloads. By default, requests route to
https://signallayer-4.polsia.app. You can also override the settlement
wallet per-request with X-Settlement-Wallet (useful for multi-tenant
fee segregation).
0x1111...
is treated as a test address. xFunnel auto-verifies these without calling the
Coinbase Commerce API. The rest of the flow (logging, fee capture, upstream
routing) runs identically. Use the Live Demo or API Playground on this page
to fire synthetic requests.
X-Request-Hash header is used as a deduplication key.
If you send the same request hash twice within a short window, the second request
returns the cached response. Use a SHA-256 of your actual binary payload as the
request hash to guarantee idempotency for identical payloads. Different payloads
always produce different request hashes.
bridge_metrics
(latency, upstream status, error type, timestamp) and one in
bridge_tx_logs (from address, to address, amount, currency, chain,
fee collected, status, per-stage latency). Transaction logs are also written to
stdout (Render log capture) in structured JSON format with a [bridge]
prefix. Live funnel stats available at GET /api/v1/metrics.
CDP_SETTLEMENT_WALLET (your ETH address on Base where fees accumulate)
and COINBASE_CDP_API_KEY (from your Coinbase Commerce dashboard).
Changes take effect on the next deploy. Placeholder values show a startup warning —
payments won't process until real credentials are configured.