Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Spec: x402 ↔ MPP bridge
Status: active. Contract version: 1. Load-bearing for api/_lib/bnb/mpp-server.js,
api/_lib/bnb/mpp-buyer.js, and any endpoint that advertises both x402 and MPP.
This is a contract, not a tutorial (for a walkthrough see
docs/bnb-payments.md). It pins the wire-level
relationship between the x402 our catalog already speaks and BNB Chain's MPP.
1. Protocol identity
MPP's b402 layer is x402 v2 (x402Version === 2), CDP wire-shape
compatible. There is no separate envelope: the 402 body, the X-PAYMENT
request header, and the X-PAYMENT-RESPONSE receipt header are identical to
x402 v2. A "dual-protocol" endpoint therefore does not run two payment stacks —
it advertises additional accepts[] entries and routes settlement by network.
2. Credential mapping
| Credential | x402 (Solana/Base) | MPP (BNB Chain) | Bridged by this repo |
|---|---|---|---|
EIP-3009 transferWithAuthorization |
Base (eip155:8453) |
eip155:56 / eip155:97 |
yes — same primitive, different network/facilitator |
permit2-exact |
— | b402 | parseable, not settled here (documented gap) |
Solana signed VersionedTransaction |
Solana | — | n/a |
The bridge is EIP-3009-only. A b402 permit2 signature can never double as
an x402 EIP-3009 credential and vice-versa. mpp-server.js rejects any non-eip3009
payload on the MPP path with unsupported_credential (HTTP 400); mpp-buyer.js
refuses to pay a BNB offer that is not eip3009 (code: 'unsupported_credential').
3. Network routing (the dispatch rule)
A payment is an MPP payment iff its accepted.network is a BNB network:
MPP_NETWORKS = { bscMainnet: 'eip155:56', bscTestnet: 'eip155:97' }
- Server:
looksLikeMppPayment(req)decodesX-PAYMENTand returns true only for these networks. A dual-protocol endpoint routes true →mpp-server.js(b402 facilitator); everything else (Solana, Base, no payment) → the existing x402 handler, untouched. - Buyer:
mpp-buyer.jsonly selectsaccepts[]entries whose network is inMPP_BUYER_NETWORKS = ['eip155:56','eip155:97'].
4. Header precedence
There is exactly one X-PAYMENT header, so precedence is by network, not by
header name:
- Decode
X-PAYMENT. If it fails to decode → the endpoint's x402 handler owns the request (it may still be a valid x402 payment in another shape). - If it decodes to a BNB network → MPP path. The x402 handler is not invoked.
- If it decodes to a non-BNB network → x402 path. The MPP path is not invoked.
- No
X-PAYMENT→ x402 path emits its 402 menu. A dual-protocol endpoint MAY also advertise an MPPaccepts[]entry in that menu and SHOULD set theX-Accept-Payment-MPP: <route>discovery header.
An endpoint MUST NOT settle the same request on both rails. On the MPP path the settle order is verify (off-chain, free) → run the resource → settle (on-chain), mirroring x402, so a failed request never moves funds.
5. Requirement pinning (security)
X-PAYMENT is attacker-controlled. Before any facilitator call, mpp-server.js:
- Full-shape-gates the decoded payload (
isEip3009PaymentPayload). - Pins every buyer-echoed field to the server's own requirements —
network,asset,payTo,amount,schememust all match. A self-consistent payload naming a different recipient/asset/amount is rejected locally (offer_mismatch, HTTP 400), never forwarded. - Recovers the payer (
recoverEip3009Payer) and requires it to equalauthorization.from.
6. Replay guarantees
Each EIP-3009 credential carries a single-use 32-byte nonce. mpp-server.js
reserves mpp:nonce:<network>:<asset>:<nonce> in Redis with SET NX PX (15 min
TTL) at verify time; a second presentation returns replay (HTTP 409). When
Redis is unavailable it falls back to a process-local guard — defence in depth
only, because the on-chain EIP-3009 nonce is itself single-use, so a landed
transfer can never be doubled even if the off-chain guard is bypassed.
7. Settlement outcomes (the caller's state machine)
| Result | HTTP | Meaning |
|---|---|---|
ok:true |
200 | settled; X-PAYMENT-RESPONSE attached |
no_payment |
402 | no X-PAYMENT; return the challenge |
unsupported_credential / wrong_network / offer_mismatch / bad_signature |
400 | rejected before settle; no funds moved |
replay |
409 | credential already used |
verify_failed / settle_failed |
402 | facilitator declined |
mpp_not_configured |
503 | verified but B402_* merchant creds absent — no receipt fabricated |
facilitator_unreachable |
502 | settle-phase transport error → state UNKNOWN; reconcile on-chain before treating as unpaid |
A 502 from the settle phase is the one non-idempotent case: b402 may already have broadcast the transfer. The nonce is single-use, so a buyer retry is value-safe, but the merchant MUST reconcile on-chain rather than assume the payment is absent.
8. Referenced code paths
api/_lib/bnb/mpp-server.js—mppRequirements,mppChallenge,mppVerify,mppSettle,looksLikeMppPayment, replay guard.api/_lib/bnb/mpp-buyer.js—mppFetch,selectRequirement, cap enforcement.api/x402/three-intel.js— the reference dual-protocol endpoint.@bnb-chain/mpp/b402— the shared x402 v2 primitives (buildEip3009Payment,decodeXPayment,recoverEip3009Payer,B402Client).