Maestro Bitcoin

Maestro Bitcoin Skill

This skill is intentionally simple: query Maestro APIs directly with x402.

Default Production Mode (Use First)

• Preferred network for production calls: eip155:1 (Ethereum mainnet).
• Secondary network: eip155:8453 (Base mainnet), only when user asks for Base or approves fallback.
• Use production hosts by default.
• Use dev. host variants only when user explicitly asks for testing/staging.
• Do not switch to testnet automatically for mainnet requests.

Minimal Prerequisites To Request

Ask for the smallest possible set of inputs:

• Wallet path A (raw signer): PRIVATE_KEY for a dedicated EVM wallet.
• Wallet path B (managed signer): CDP Agent Wallet already provisioned in runtime.
• Optional WALLET_NETWORK (default to eip155:1 if omitted).

Funding requirements (only what is needed to pay):

• Enough USDC on the selected network for the current challenge amount.
• Small ETH balance for gas on that same network.

Never ask for API keys for x402 flow. Never ask for more wallet data than required.

CDP Agent Wallet Option

Agents may use Coinbase CDP Agent Wallet instead of raw private keys when user/runtime already supports it:

• Docs: https://docs.cdp.coinbase.com/agentic-wallet/welcome
• Use CDP-provided signer/account for x402 signing.
• Keep the same network-selection rule: prefer eip155:1 for mainnet.
• Request only missing CDP prerequisites if unavailable; do not request both CDP secrets and PRIVATE_KEY unless user asks.

Workflow

1. Read endpoint specs from https://docs.gomaestro.org/bitcoin (or linked REST references there). All docs pages are available as markdowns by simply appending .md to the URL path, e.g. https://docs.gomaestro.org/bitcoin/blockchain-indexer-api/addresses/utxos-by-address.md.
2. Send the endpoint request without api-key.
3. If the gateway returns 402 Payment Required, parse PAYMENT-REQUIRED (or response body equivalent).
4. Select the payment option that matches WALLET_NETWORK (default eip155:1).
5. Sign and retry with payment header(s): PAYMENT-SIGNATURE and/or X-PAYMENT depending client implementation.
6. Return the API body and payment settlement metadata (PAYMENT-RESPONSE or X-PAYMENT-RESPONSE) when present.

x402 Headers

• PAYMENT-REQUIRED: payment challenge from the gateway.
• PAYMENT-SIGNATURE: signed payment proof from the client.
• PAYMENT-RESPONSE: payment/settlement metadata on success.
• X-PAYMENT / X-PAYMENT-RESPONSE: alternate header pair used by some clients.

Explorer Transaction Lookup

After successful payment, extract transaction and network from PAYMENT-RESPONSE (or X-PAYMENT-RESPONSE) and return an explorer link.

• eip155:1 (Ethereum mainnet): https://etherscan.io/tx/<transaction_hash>
• eip155:8453 (Base mainnet): https://basescan.org/tx/<transaction_hash>

If explorer mapping is unknown, still return:

• raw transaction hash
• network id from response
• note that explorer URL could not be resolved automatically

Recommended Client Stack

Prefer current @x402/* client packages for compatibility with CAIP-2 networks such as eip155:1 and eip155:8453.

• Recommended: @x402/fetch + @x402/evm.
• Avoid older x402-fetch/x402 v1-only assumptions when challenge uses CAIP-2 network IDs.

General Transaction Initiation (Without x402 SDK)

If @x402/* is unavailable, agents may initiate payment manually with any EVM signer.

1. Send request and capture 402 challenge (PAYMENT-REQUIRED header or JSON body).
2. Pick the payment option matching WALLET_NETWORK (default eip155:1).
3. Build EIP-712 TransferWithAuthorization message using challenge fields: asset, payTo, amount, maxTimeoutSeconds, and token metadata in extra.
4. Sign typed data with wallet key.
5. Build payment payload with: x402Version, scheme, network, and signed authorization payload.
6. Base64-encode the payload and retry request with PAYMENT-SIGNATURE and/or X-PAYMENT.
7. Verify success via HTTP 200 and PAYMENT-RESPONSE/X-PAYMENT-RESPONSE.

Manual flow is valid, but preferred only as fallback because protocol/encoding details are easy to get wrong.

Rules For Agents

• Do not hardcode payment amount, recipient, or network; use PAYMENT-REQUIRED each time.
• If user asked for mainnet, enforce eip155:1 selection unless user explicitly requested Base mainnet.
• Ask before any fallback network (eip155:8453) or any move to testnet.
• Support both wallet modes: PRIVATE_KEY signer or CDP Agent Wallet signer.
• If user intent is unclear, confirm before sending the first paid mainnet request (real USDC spend).
• Re-run challenge flow if payment verification fails or challenge details change.
• If no funded wallet is available, stop and ask only for missing minimum inputs.
• Keep implementation direct and endpoint-specific.

Minimal Failure Handling

If paid retry returns 402 again, report concise diagnostics:

1. Selected payment network.
2. Challenge amount and token.
3. Wallet address used for signing.
4. Next required user action: fund USDC and gas on the selected mainnet network, then retry.

Primary Source

• https://docs.gomaestro.org/bitcoin