Skip to main content
The Shoal API supports two authentication methods. You can use either one — they work on all endpoints.

​
Option 1: API Key (Bearer Token)

Send your API key in the Authorization header using the Bearer scheme. 
Authorization: Bearer <YOUR_API_KEY>
Get your API key at app.shoal.xyz.

​
Error Responses

StatusBodyCause
401{ "error": "Authorization header missing or malformed" }No header or bad format
401{ "error": "API key missing" }Empty key after Bearer
401{ "error": "Invalid API key" }Key not found

​
Option 2: Pay-Per-Request (MPP)

No API key needed. The Shoal API supports the Machine Payments Protocol (MPP) — an open standard for HTTP 402 pay-per-request access. Price: $0.01 per request, paid via Stripe (card or Link).

​
How It Works

  1. Send a request with no Authorization header (or with Authorization: Payment ...)
  2. The API returns 402 Payment Required with a WWW-Authenticate: Payment challenge
  3. Your client pays via Stripe and retries with the payment credential
  4. The API verifies payment and returns the response with a Payment-Receipt header

​
Quick Start

Use the mppx CLI to test: 
npx mppx account create
npx mppx pay GET https://api.shoal.xyz/v1/signal/top

​
SDK Support

MPP clients are available for TypeScript, Python, and Rust: 
npm install mppx        # TypeScript
pip install pympp        # Python
cargo add mpp            # Rust
See the MPP integration guide for code examples.