FAQ

Should my agent call the gateway or the upstream API directly?

Use the Caddy gateway URL. x402 enforcement, payment headers, and settlement happen at the gateway edge. Discovery/OpenAPI should also be fetched through the gateway in production.

Why do paid routes return 402 first?

That is expected. The gateway advertises payment requirements through PAYMENT-REQUIRED so your client can sign and retry with PAYMENT-SIGNATURE.

Does Amarok hold keys or submit orders?

No. Amarok never stores mnemonics, never signs payments, and never submits orders. Execution quotes return unsignedTxnsBase64 with meta.executionSubmitted: false. Your agent signs and submits via its own algod.

Does the website sign payments for me?

No. Payment signing stays client-side in your agent or wallet integration. This site only documents the flow and links to machine-readable contracts.

Which USDC asset id should I expect?

Use the asset id published in discovery/OpenAPI x402 metadata for the target network. On Algorand mainnet the default documented id is 31566704.

Can I browse opportunity data on this website without paying?

No. This site is onboarding documentation only. Research and execution-quote data remains API-only behind x402 payment gates. Free probes include discovery, OpenAPI, and execution shapes.

Which MCP URL should I use?

Production remote MCP: https://amarok-mcp.compx.io/mcp (Streamable HTTP). Verify with https://amarok-mcp.compx.io/.well-known/mcp. Discovery advertises this URL in mcpServer.url.

Do I need a wallet mnemonic in the MCP server?

No. The remote MCP is walletless. Your agent or client wallet signs USDC payments and passes paymentSignature when retrying paid MCP tools. Never put mnemonics in MCP server configuration.

Should I use MCP or direct HTTP?

Use MCP when your agent host supports MCP tools (Cursor, Claude Desktop). Use direct HTTP when building a custom client against the Caddy gateway. Both hit the same public gateway for paid data; MCP is a typed pass-through wrapper.

How do I test locally?

Run the protocol API and Caddy gateway from the monorepo, then point website env vars to your local gateway URL during development. Production API references in this site use https://amarok-api.compx.io.