Protocol

Session Lifecycle

Every paid agent interaction runs inside an MPP session. Sessions enforce budget boundaries, debit paid tool calls, and preserve a durable refund path for any unspent XLM.

State Machine

pending_funding → active → spent → withdraw_pending → withdrawn
                    ↘        ↘
                  expired   withdrawn

States

State	Description
pending_funding	Session created. Waiting for the user to send XLM on Stellar with the funding memo.
active	Funded and verified. Marketplace routes can debit the session for paid tool calls.
spent	The session budget has been fully consumed by reconciled execution charges.
withdraw_pending	A withdrawal or refund submission is in flight or needs manual recovery.
withdrawn	Any refundable XLM has been returned to the user wallet, or no withdrawal was required.
expired	The session aged out or could not be activated safely. Create a new MPP session.

Funding Flow

1. POST /api/marketplace/mpp/session → returns funding destination + funding memo

2. User signs the exact XLM funding payment in Freighter

3. POST /api/marketplace/mpp/session/activate with the funding tx hash

4. Backend verifies the on-chain payment and unlocks the session for debits

Budget Enforcement

The durable execution ledger is the source of truth for session spending. Each paid tool charge debits the active MPP session, and session balance is reconciled from charged, fulfilled, and refunded executions so the UI never depends on transient local state.

Refund

When the user ends the session, the backend calculatesinitialBudget - reconciled chargesand sends the refundable XLM back to the user wallet on Stellar. If the withdrawal submission fails, the session enters withdraw_pendingso the failure is durable instead of leaving the UI stuck in a transient state.