Examples
All examples use the public Caddy gateway URL. Replace placeholders before running paid retries.
MCP discovery tool
After connecting to https://amarok-mcp.compx.io/mcp, call amarok_get_discovery for
the same route catalog as HTTP /discovery (free tool).
# Example: MCP client invokes amarok_get_discovery (no payment required)
# Paid tools: first call returns PAYMENT_REQUIRED; retry with paymentSignatureDiscovery fetch (HTTP)
curl -s https://amarok-api.compx.io/discovery | jq '.routes[] | {path, access, summary}'OpenAPI fetch
curl -s https://amarok-api.compx.io/openapi.json | jq '.info, (.paths | keys)'MCP paid tool retry shape
Paid MCP tools mirror the HTTP x402 flow. First invocation returns payment metadata; retry
passes the signed payload as paymentSignature (tool argument, not an HTTP header).
// 1) amarok_list_opportunities({})
// -> PAYMENT_REQUIRED + paymentRequiredHeader metadata
// 2) amarok_list_opportunities({
// paymentSignature: "<base64-json-payload>"
// })
// -> opportunity dataSigned retry shape (HTTP)
The website does not sign payments. Your agent/client wallet must build this payload.
{
"x402Version": 2,
"scheme": "exact",
"network": "algorand-mainnet",
"accepted": { /* selected accept option from PAYMENT-REQUIRED */ },
"payload": {
"paymentGroup": ["<base64-signed-txn>"],
"paymentIndex": 0
},
"paymentRequired": { /* decoded PAYMENT-REQUIRED */ }
}Sample response payloads
These are illustrative placeholders of the response contract, not live paid data. Live responses
vary; field semantics should match OpenAPI when the gateway is public. Full schemas:
OpenAPI.
Ranked opportunities
GET /v1/alpha/opportunities — ranked LP reward, maker/spread, and parity lanes.
curl -i https://amarok-api.compx.io/v1/alpha/opportunitiesSample response (200, placeholder)
{
"data": [
{
"kind": "lp_reward",
"marketAppId": 3100000001,
"slug": "SAMPLE-MARKET",
"title": "Sample Alpha Arcade Market (placeholder)",
"estimatedUsdPerDay": "12.40",
"confidence": 0.82,
"notes": "Illustrative snapshot — not live paid data."
},
{
"kind": "maker_spread",
"marketAppId": 3100000002,
"slug": "SAMPLE-SPREAD",
"title": "Sample maker/spread opportunity",
"estimatedUsdPerDay": "4.15",
"confidence": 0.71,
"notes": "Illustrative snapshot — not live paid data."
}
],
"meta": {
"asOf": "2026-07-23T00:00:00.000Z",
"source": "placeholder",
"note": "Replace with live discovery-backed samples when API is public."
}
}Market deep dive
GET /v1/alpha/markets/{marketAppId} — single-market book tops and related slice.
curl -i https://amarok-api.compx.io/v1/alpha/markets/3100000001Sample response (200, placeholder)
{
"data": {
"marketAppId": 3100000001,
"slug": "SAMPLE-MARKET",
"title": "Sample Alpha Arcade Market (placeholder)",
"status": "live",
"book": {
"bestBid": "0.42",
"bestAsk": "0.44",
"mid": "0.43",
"spreadBps": "465"
},
"relatedOpportunities": 2
},
"meta": {
"asOf": "2026-07-23T00:00:00.000Z",
"source": "placeholder",
"note": "Illustrative sample — not live paid data."
}
}Portfolio by address
GET /v1/alpha/portfolio/{address} — paid own-wallet Alpha state (balances,
positions with mark-to-market, open orders, bid escrow). Same DTO family as free
/public/agents/ghillie/portfolio (Ghillie remains the hardcoded free exception).
curl -i https://amarok-api.compx.io/v1/alpha/portfolio/<agentAddress> \
-H 'PAYMENT-SIGNATURE: <base64-json-payload>'Inventory-aware advisor
POST /v1/alpha/advisor — post an authoritative snapshot (address + positions + open
orders + optional avg cost / asset ids). Returns suggested inventory exits, off-zone/underwater
cancels, resolvable claims, and size adjustments. Amarok never holds keys;
meta.executionSubmitted is always false. Empty-wallet generic quotes
remain on GET /v1/alpha/quotes.
curl -i -X POST https://amarok-api.compx.io/v1/alpha/advisor \
-H 'content-type: application/json' \
-H 'PAYMENT-SIGNATURE: <base64-json-payload>' \
-d '{
"address": "<agentAddress>",
"positions": [
{ "marketAppId": 3100000001, "yesShares": 20, "avgYesCost": 0.48 }
],
"openOrders": []
}'Unsigned execution quote
POST /v1/alpha/execution/quotes — unsigned txn groups for
alpha_place_limit_order, alpha_cancel_order,
alpha_claim, alpha_place_market_order,
alpha_merge_shares, alpha_split_shares, and
alpha_opt_in. GET /v1/alpha/parity is research-only;
compile sized YES+NO fills as two market quotes plus merge (buy-and-merge) or
split plus two market sells. meta.executionSubmitted is always
false. Partial amountShares on claim leaves remaining
outcome tokens in the wallet. Omit it to redeem the full on-chain balance
(includes ASA close-out). Groups prepend a USDC opt-in if the agent is not
opted in.
curl -i -X POST https://amarok-api.compx.io/v1/alpha/execution/quotes \
-H 'content-type: application/json' \
-H 'PAYMENT-SIGNATURE: <base64-json-payload>' \
-d '{
"agentAddress": "<agentAddress>",
"quotes": [
{
"shapeKey": "alpha_place_market_order",
"input": { "marketAppId": 3100000001, "outcome": "YES", "side": "bid", "price": 0.41, "sizeShares": 5, "slippage": 0.02, "matchingOrders": [{ "escrowAppId": 3200000001, "owner": "<makerAddress>", "quantityShares": 5 }] }
},
{
"shapeKey": "alpha_place_market_order",
"input": { "marketAppId": 3100000001, "outcome": "NO", "side": "bid", "price": 0.56, "sizeShares": 5, "slippage": 0.02 }
},
{
"shapeKey": "alpha_merge_shares",
"input": { "marketAppId": 3100000001, "amountShares": 5 }
},
{
"shapeKey": "alpha_split_shares",
"input": { "marketAppId": 3100000001, "amountShares": 5 }
},
{
"shapeKey": "alpha_opt_in",
"input": { "marketAppId": 3100000001 }
},
{
"shapeKey": "alpha_place_limit_order",
"input": { "marketAppId": 3100000001, "outcome": "YES", "side": "bid", "price": 0.42, "sizeShares": 10 }
},
{
"shapeKey": "alpha_cancel_order",
"input": { "marketAppId": 3100000001, "escrowAppId": 3200000001 }
},
{
"shapeKey": "alpha_claim",
"input": { "marketAppId": 3100000001, "assetId": 1001 }
}
]
}'Sample response (200, placeholder)
{
"asOf": "2026-07-23T00:00:00.000Z",
"staleAfterMs": 15000,
"meta": {
"executionSubmitted": false,
"source": "placeholder",
"note": "Illustrative sample — not live paid data."
},
"data": [
{
"shapeKey": "alpha_place_limit_order",
"quoteId": "00000000-0000-4000-8000-000000000001",
"warnings": [
"Resting limit order only (no immediate match legs in Amarok v1).",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 2,
"unsignedTxnsBase64": [
"<base64-txn-0>",
"<base64-txn-1>"
]
}
},
{
"shapeKey": "alpha_cancel_order",
"quoteId": "00000000-0000-4000-8000-000000000002",
"cancelIntent": {
"marketAppId": 3100000001,
"escrowAppId": 3200000001,
"orderOwner": "<agentAddress>"
},
"warnings": [
"Cancels a resting escrow via delete_escrow; sender must be the order owner.",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 1,
"unsignedTxnsBase64": [
"<base64-cancel-txn>"
]
}
},
{
"shapeKey": "alpha_claim",
"quoteId": "00000000-0000-4000-8000-000000000003",
"claimIntent": {
"marketAppId": 3100000001,
"assetId": 1001,
"amountMicro": 2000000,
"amountShares": 2,
"closedOut": false
},
"requiresOptIn": [],
"warnings": [
"Redeems resolved outcome tokens for USDC via claim; market must be resolved.",
"Partial claim: remaining outcome tokens stay in the agent wallet (no ASA close-out).",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 2,
"unsignedTxnsBase64": [
"<base64-claim-0>",
"<base64-claim-1>"
]
}
},
{
"shapeKey": "alpha_place_market_order",
"quoteId": "00000000-0000-4000-8000-000000000004",
"orderIntent": {
"marketAppId": 3100000001,
"outcome": "YES",
"side": "bid",
"priceMicro": 410000,
"quantityMicro": 5000000,
"slippageMicro": 20000,
"matcherAppId": 3078581851
},
"warnings": [
"Includes propose_a_match legs against the supplied maker escrows. Counterparties can go stale; re-quote if the book moves.",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 5,
"createEscrowIndex": 2,
"unsignedTxnsBase64": [
"<base64-mbr>",
"<base64-fund>",
"<base64-create-escrow>",
"<base64-match-pay>",
"<base64-propose-match>"
]
}
},
{
"shapeKey": "alpha_merge_shares",
"quoteId": "00000000-0000-4000-8000-000000000005",
"mergeIntent": {
"marketAppId": 3100000001,
"amountMicro": 5000000,
"amountShares": 5,
"yesAssetId": 1001,
"noAssetId": 1002
},
"requiresOptIn": [],
"warnings": [
"Merges equal YES+NO shares into USDC via merge_shares (1 YES + 1 NO = 1 USDC).",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 4,
"unsignedTxnsBase64": [
"<base64-inner-fee>",
"<base64-yes>",
"<base64-no>",
"<base64-merge>"
]
}
},
{
"shapeKey": "alpha_split_shares",
"quoteId": "00000000-0000-4000-8000-000000000006",
"splitIntent": {
"marketAppId": 3100000001,
"amountMicro": 5000000,
"amountShares": 5,
"yesAssetId": 1001,
"noAssetId": 1002,
"usdcAssetId": 1000
},
"requiresOptIn": [],
"warnings": [
"Splits USDC into equal YES+NO shares via split_shares (1 USDC = 1 YES + 1 NO).",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 3,
"unsignedTxnsBase64": [
"<base64-inner-fee>",
"<base64-usdc>",
"<base64-split>"
]
}
},
{
"shapeKey": "alpha_opt_in",
"quoteId": "00000000-0000-4000-8000-000000000007",
"optInIntent": {
"marketAppId": 3100000001,
"assetIds": [
1000,
1001,
1002
]
},
"requiresOptIn": [
1000,
1001,
1002
],
"warnings": [
"ASA opt-in axfers only; no market app call. Use before funding legs that warn about missing opt-ins.",
"Amarok never signs or submits; agent must sign unsignedTxnsBase64 and sendRawTransaction."
],
"group": {
"txnCount": 3,
"unsignedTxnsBase64": [
"<base64-optin-usdc>",
"<base64-optin-yes>",
"<base64-optin-no>"
]
}
}
]
}