Protocol

Stellar MPP Protocol

How StellarNotherc implements the Machine Payment Protocol for agent-to-service commerce on Stellar.

What is Stellar MPP?

The Machine Payment Protocol (MPP) is Stellar's native protocol for agent-to-service payments. It repurposes the HTTP 402 “Payment Required” status code with a standard challenge/credential flow: the server issues a WWW-Authenticate: Payment challenge, the client pays on-chain and replies with an Authorization: Payment credential.

StellarNotherc uses MPP in two modes: charge for per-request micropayments and session-funded execution for budgeted multi-step workflows. Both settle on Stellar mainnet with native XLM.

Payment Flow (Charge Intent)

1. Client → GET /api/marketplace/remittance/fx

2. Server ← HTTP 402 + WWW-Authenticate: Payment id="...", realm="...", method="stellar", intent="charge", request="<base64url>"

3. Client → pays XLM on Stellar with hash memo (SHA-256 of challenge ID)

4. Client → retries with header Authorization: Payment <base64url credential>

5. Server verifies challenge HMAC, hash memo, and on-chain payment

6. Server ← HTTP 200 + tool response + SP1 proof metadata

Session Flow (Channel Intent)

1. User funds an MPP marketplace session with XLM on Stellar

2. Client sends requests with header x-mpp-session: <session-id>

3. Server charges the session budget per tool call (no additional on-chain tx)

4. On session end: unspent budget refunded on-chain

Payment Verification

For charge-intent payments, the credential includes the Stellar transaction hash. The server:

Verifies the challenge ID HMAC (ensures the challenge was issued by this server)
Checks the hash memo binds the transaction to the specific challenge
Queries Horizon for the transaction and its operations
Verifies the payment matches: correct destination, native asset (XLM), and amount
Marks the challenge as consumed (replay protection via Cloudflare KV)

MPP + SP1 Proofs

After payment verification, every tool purchase generates an SP1 zero-knowledge proof attesting to the payment's correctness. The proof metadata is included in the tool response:

{
  "quotes": [...],
  "marketplacePayment": {
    "rail": "mpp",
    "payment_status": "charged",
    "mppChargeHash": "abc123...",
    "proof_status": "verified",
    "proof_id": "...",
    "proof_kind": "tool_purchase_receipt",
    "proof_receipt_digest": "0x..."
  }
}

Protected Endpoints

Endpoint	Price	Description
/api/marketplace/remittance/fx	0.005 XLM	FX quote with SDEX rate comparison
/api/marketplace/remittance/fees	0.005 XLM	Fee estimate
/api/marketplace/portfolio/report	0.165 XLM	Full portfolio report
/api/marketplace/portfolio/pretrade	0.165 XLM	Pre-trade approval gate
/api/marketplace/portfolio/risk	0.005 XLM	Risk analysis
/api/marketplace/portfolio/stress	0.005 XLM	Stress test
/api/marketplace/portfolio/macro	0.005 XLM	Macro overlay
/api/marketplace/portfolio/rebalance	0.005 XLM	Rebalance suggestions

Why Stellar for MPP

5-second finality — MPP charge payments are synchronous HTTP. Settlement must complete within the same request cycle.
~$0.00001 fees — Micropayments only work if the fee doesn't exceed the payment. Stellar fees are negligible.
Native XLM — First-class native-asset support without issuer or trustline dependencies.
99.99% uptime — Agents run 24/7. Network reliability is non-negotiable.

Implementation

The MPP charge server logic lives in lib/stellarremit/mpp-charge.ts. Two functions handle the full lifecycle:

createPaymentRequiredResponse() — Returns HTTP 402 with WWW-Authenticate challenge
verifyMppChargeCredential() — Verifies the Authorization credential against on-chain Stellar payment