Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt

Use this file to discover all available pages before exploring further.

The Shoal API supports the Machine Payments Protocol (MPP) — an open standard by Tempo and Stripe that enables pay-per-request access using HTTP 402. This is ideal for AI agents, one-off scripts, and services that need Shoal data without managing API keys.
MPP/x402 is available on the public paid surface, not every /v1/* route. Bulk and account-management endpoints remain API-key-only.

​
Pricing

Per request$0.01 USD
Payment methodsStripe (card, Link)
BillingPer-request, no subscription

​
How It Works

Client                          Shoal API
  |                                |
  |  GET /v1/signal/top            |
  |------------------------------->|
  |                                |
  |  402 Payment Required          |
  |  WWW-Authenticate: Payment ... |
  |<-------------------------------|
  |                                |
  |  (client pays via Stripe)      |
  |                                |
  |  GET /v1/signal/top            |
  |  Authorization: Payment ...    |
  |------------------------------->|
  |                                |
  |  200 OK                        |
  |  Payment-Receipt: ...          |
  |<-------------------------------|

​
Quick Start

Install the MPP CLI and create a test account: 
npx mppx account create
Make a paid request: 
npx mppx pay GET https://api.shoal.xyz/v1/signal/top

​
TypeScript

import { MppClient, stripe } from "mppx/client";

const client = MppClient.create({
  methods: [stripe()],
});

const response = await client.fetch(
  "https://api.shoal.xyz/v1/signal/top?limit=10"
);
const data = await response.json();

​
Python

from pympp import MppClient

client = MppClient(methods=["stripe"])

response = client.get(
    "https://api.shoal.xyz/v1/signal/top",
    params={"limit": 10},
)
data = response.json()

​
Rust

use mpp::MppClient;

let client = MppClient::builder()
    .stripe()
    .build();

let response = client
    .get("https://api.shoal.xyz/v1/signal/top?limit=10")
    .send()
    .await?;

​
Notes

  • MPP works on Shoal’s public paid endpoints
  • No API key or account signup required
  • Each request is independently paid and verified
  • Payment receipts are returned in the Payment-Receipt response header
  • Learn more at mpp.dev