maestro-api

name	maestro-api
description	Query Maestro APIs over HTTP using the SIWX + JWT + x402 credit purchase flow. Resolve the exact endpoint from docs.gomaestro.org before requesting or paying.

Maestro API

Use this skill when the user wants a direct HTTP call to a Maestro endpoint. The intended path is short: resolve the exact operation page, send the real request, satisfy the live SIWX challenge, and only buy credits if the server still returns 402.

Fast Path

1. Resolve the exact operation page in docs.gomaestro.org.
2. Read the page's .md form and use its OpenAPI block as the source of truth.
3. Build the request URL from servers: plus the operation path.
4. Send the real request with no auth or payment headers.
5. If the response is 200, return the data.
6. If the response is 402 with extensions.sign-in-with-x, sign the SIWX challenge and retry the exact same request with sign-in-with-x.
7. If that retry returns 200, return the data.
8. If that retry returns 402 plus Authorization: Bearer <jwt>, buy credits from the latest accepts[] entry and retry the exact same request with Authorization and X-PAYMENT.
9. Reuse the JWT for follow-up queries until it expires or Maestro asks for more credits.

Resolve Endpoint From Docs

Use docs only to find the exact operation page. Do not browse broadly once you have it.

• Start with https://docs.gomaestro.org/llms.txt only if the operation page is not already obvious.
• Prefer operation pages over quick-start pages.
• Read the .md page and extract:
  • operation line -> path
  • servers: -> base URL for the chosen network
  • parameters and body schema -> request shape
• Combine server.url + path.
• Do not derive the REST host from the SIWX domain or URI.
• Useful Bitcoin routing shortcuts:
  • confirmed chain data -> Blockchain Indexer API
  • mempool-aware or pending data -> Mempool Monitoring API
  • mempool.space-style routes -> Esplora API
  • wallet balances or wallet activity -> Wallet API

Minimal Prerequisites

Ask only for what is required to sign and pay:

• PRIVATE_KEY, or a runtime CDP wallet signer
• enough USDC and native gas on one network from the live 402 response
• no API key

Request Rules

• Keep method, path, query parameters, and body unchanged across the unauthenticated request, the SIWX retry, and the paid retry.
• Always use the latest 402 response for supported_chains, accepts[], asset, pay_to, and price limits.
• Confirm before the first paid mainnet request.
• If a paid retry still fails, report:
  • docs page used
  • selected network
  • selected amount
  • signer address
  • minimal next action

Read Only When Needed

Read SIWX + x402 Reference only when you need the exact signing or header details:

• sign-in-with-x payload format
• X-PAYMENT payload format
• EIP-4361 SIWX message template
• ERC-3009 EIP-712 domain and message fields
• response header meanings
• failure cases and common pitfalls