Skip to main content
mpp_fetch fetches an MPP-gated URL by committing a payment against your active payment channel. Unlike x402_fetch, this does not broadcast a Stellar transaction on every call — instead, the Hub advances the channel state off-chain. All committed amounts are settled in a single on-chain transaction when you call mpp_close_session. This makes mpp_fetch ideal for high-frequency, low-cost API calls where submitting a Stellar transaction per request would be impractical.

​
Prerequisites

You must have an active MPP session before calling mpp_fetch. Open one with mpp_open_session. If no session is open when you call mpp_fetch, the tool returns an error immediately without making any network request.

​
Parameters

​
url
string
required
The MPP-gated URL to fetch. Must be a valid HTTP or HTTPS URL. The server at this URL must support the MPP payment protocol and accept channel payment proofs from the Hub.

​
Response

​
Success

Success response
{
  "status": "ok",
  "data": {
    "response_body": "<content returned by the server>",
    "amount_committed_usdc": 0.001,
    "channel_remaining_usdc": 0.987,
    "channel_id": "ch_4f8a2b1e"
  }
}
​
status
string
Always "ok" on success.
​
data.response_body
string
The response body returned by the MPP-gated server.
​
data.amount_committed_usdc
number
The USDC amount committed to the channel for this specific call.
​
data.channel_remaining_usdc
number
How much USDC remains in the channel budget after this commitment.
​
data.channel_id
string
The ID of the active channel used for this request.

​
Error — no active session

No active session
{
  "status": "error",
  "reason": "No active MPP session. Call mpp_open_session first."
}

​
Error — budget exhausted

Budget exhausted
{
  "status": "error",
  "reason": "Channel budget exhausted: 0.00 USDC remaining"
}

​
Example

Tool call
{
  "tool": "mpp_fetch",
  "input": {
    "url": "https://api.example.com/stream/tick"
  }
}
Response
{
  "status": "ok",
  "data": {
    "response_body": "{\"price\": 0.9821, \"asset\": \"XLM/USDC\"}",
    "amount_committed_usdc": 0.001,
    "channel_remaining_usdc": 0.987,
    "channel_id": "ch_4f8a2b1e"
  }
}
Use the demo_url returned by mpp_open_session to test mpp_fetch without a live merchant server. Call mpp_status periodically to confirm your remaining budget before making a large batch of requests.