Skip to main content
mpp_open_session opens a Micropayment Protocol (MPP) payment channel and locks a USDC budget into it. Once a session is open, each call to mpp_fetch makes an off-chain channel commitment against that budget — no on-chain transaction is needed per request. The channel is settled on Stellar only when you call mpp_close_session, at which point any unused funds are returned to your wallet. Budget locking uses ignoreSpendCaps internally, meaning the channel-open operation itself does not count as a regular spend event against your daily policy cap. The actual spend is recorded when the channel is settled on close.

​
Parameters

​
budget_usdc
number
required
Total USDC budget to lock into this channel. Must be a positive finite number. This is the maximum you can spend across all mpp_fetch calls within the session. Any portion not consumed is refunded when the session is closed.
​
recipient
string
The Stellar address (G…) of the payment recipient — typically the merchant or API provider running the MPP-gated service. When omitted, the Hub assigns the channel recipient based on the first mpp_fetch URL or a preconfigured default. Must be a valid Stellar public key starting with G.

​
Response

​
Success

Success response
{
  "status": "ok",
  "data": {
    "channel_id": "ch_4f8a2b1e",
    "budget_usdc": 1.00,
    "recipient": "GDEMO7EXAMPLE8STELLARADDRESS9FORMPPCHANNEL0RECIP",
    "demo_url": "https://hub.nebula.dev/mpp-demo/ch_4f8a2b1e",
    "session_state": "open"
  }
}
​
status
string
Always "ok" on success.
​
data.channel_id
string
Unique identifier for the newly opened MPP channel. Retained by the Hub for the lifetime of the session.
​
data.budget_usdc
number
The USDC budget locked into this channel, matching your input.
​
data.recipient
string
The Stellar address of the channel recipient.
​
data.demo_url
string
A Hub-hosted test URL you can pass directly to mpp_fetch to verify the session is working without needing your own merchant server. Useful during development and debugging.
​
data.session_state
string
The current state of the session. Will be "open" immediately after creation.

​
Error

Error response
{
  "status": "error",
  "reason": "Insufficient USDC balance to lock channel budget of 1.00 USDC"
}

​
Next steps

Once your session is open, use mpp_fetch to fetch MPP-gated URLs within this channel. Use mpp_status at any time to check remaining budget. Call mpp_close_session when you are finished to settle on-chain and reclaim unused funds.

​
Example

Tool call
{
  "tool": "mpp_open_session",
  "input": {
    "budget_usdc": 1.00,
    "recipient": "GDEMO7EXAMPLE8STELLARADDRESS9FORMPPCHANNEL0RECIP"
  }
}
Response
{
  "status": "ok",
  "data": {
    "channel_id": "ch_4f8a2b1e",
    "budget_usdc": 1.00,
    "recipient": "GDEMO7EXAMPLE8STELLARADDRESS9FORMPPCHANNEL0RECIP",
    "demo_url": "https://hub.nebula.dev/mpp-demo/ch_4f8a2b1e",
    "session_state": "open"
  }
}
Only one MPP session can be active at a time per Nebula wallet. Opening a new session while one is already open will return an error. Close the existing session first with mpp_close_session.