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 over POST; GET /mcp returns 405 because SSE is not offered). Verify with https://amarok-mcp.compx.io/.well-known/mcp. For local development, run @amarok/mcp over stdio — see MCP docs.

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.

Why did amarok_get_scan return timedOut or capped?

MCP clients typically abort around ~60s. Production scan caps (ALPHA_SCAN_ORDERBOOK_LIMIT=12, ALPHA_MAX_MARKETS_PER_SCAN=0, ALPHA_SCAN_TIMEOUT_MS=45000) keep a cold orderbook pass inside that budget. capped means live markets were truncated; timedOut means the 45s orderbook budget elapsed and remaining books were skipped. Ranking tools share the same pass. Raise the caps only for HTTP clients that can wait longer.

Are Polymarket and Kalshi execution routes?

No. /v1/polymarket/* and /v1/kalshi/* are scan-only families. Each has its own in-process TTL cache (not Alpha scanCache; not Redis/KV). Explicitly deferred: execution, WebSockets, Perps, cross-venue matching, quotes/bundle SKUs, watchlist/history, and GET /quotes. Light GETs can use AMAROK-SESSION; neither venue /scan is session-covered. See venues.

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 AMAROK_API_URL (stdio MCP) or website env vars at your local gateway. Cursor / Claude Desktop configs for the hosted Worker are on the quickstart. Paid tools spend mainnet USDC; use npm run test -w @amarok/mcp (in-process stub) when you need a no-spend dry-run.