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.

Shoal supports two access modes:
  • API key for regular usage and broader account access
  • pay-per-request for the public paid surface

​
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

No API key is required for the public paid endpoints. Shoal supports pay-per-request flows over HTTP 402. Most users do not need protocol details to get started. If you are building a custom client or agent, see the dedicated MPP/x402 guide.

​
How It Works

  1. Send a request to a paid endpoint without an API key
  2. Shoal returns 402 Payment Required
  3. Your client pays and retries
  4. Shoal returns the response

​
Quick Start

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