MCP server

The canix402 MCP is a remote, walletless wrapper over the public Caddy gateway. Agents connect over Streamable HTTP, call typed tools for discovery, opportunity data, and multi-router swaps, and handle x402 payment signing on the client side.

Endpoint

Transport: streamable-http
MCP URL: https://canix402-mcp.compx.io/mcp
Metadata: https://canix402-mcp.compx.io/.well-known/mcp
Health: https://canix402-mcp.compx.io/health

The MCP never stores mnemonics or private keys. Paid tools return structured payment requirements on the first call; your agent signs USDC client-side and retries with paymentSignature.

Swaps

canix_get_quote — free, parallel multi-router quote from POST /swaps/quote.
canix_optin — free output-asset and application opt-ins from POST /swaps/optin.
canix_swap — paid swap transaction response from POST /swaps/transactions, with a 0.005 USDC fallback price.

Pass the quote returned by canix_get_quote into the opt-in or swap tool. The MCP does not retain quotes, sign transactions, or submit them; gateway responses pass through to the caller.

// Free quote
canix_get_quote({
  address: "YOUR_ALGORAND_ADDRESS",
  fromAssetId: 0,
  toAssetId: 31566704,
  amount: "1000000",
  type: "fixed-input"
})

// Free opt-in (pass quote from previous step)
canix_optin({
  address: "YOUR_ALGORAND_ADDRESS",
  quote: { /* quote data */ }
})

// Paid swap — preflight, then retry with paymentSignature
canix_swap({
  address: "YOUR_ALGORAND_ADDRESS",
  quote: { /* fresh quote data */ },
  slippage: 0.005
})
canix_swap({
  address: "YOUR_ALGORAND_ADDRESS",
  quote: { /* fresh quote data */ },
  slippage: 0.005,
  paymentSignature: "<base64-json-payload>"
})

Positions and execution quotes (paid tools)

// Positions
canix_get_positions({ address: "YOUR_ALGORAND_ADDRESS" })
canix_get_positions({
  address: "YOUR_ALGORAND_ADDRESS",
  paymentSignature: "<base64-json-payload>"
})

// Claim desk
canix_list_claimable({ address: "YOUR_ALGORAND_ADDRESS" })
canix_list_claimable({
  address: "YOUR_ALGORAND_ADDRESS",
  paymentSignature: "<base64-json-payload>"
})

// Eligibility
canix_check_eligibility({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  opportunityIds: ["reti-staking-12"]
})
canix_check_eligibility({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  opportunityIds: ["reti-staking-12"],
  paymentSignature: "<base64-json-payload>"
})

// Intent compiler (consume this instead of forking a local compiler)
canix_get_plan({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  budget: { assetId: 0, amount: "1000000" },
  constraints: { noNewBorrows: true, executionReadyOnly: true },
  opportunityIds: ["reti-staking-12"]
})
canix_get_plan({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  budget: { assetId: 0, amount: "1000000" },
  constraints: { noNewBorrows: true, executionReadyOnly: true },
  opportunityIds: ["reti-staking-12"],
  paymentSignature: "<base64-json-payload>"
})

// Swap-aware enter compose (hold asset A, enter this opportunity)
canix_compose_enter({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  opportunityId: "reti-staking-12",
  fromAssetId: 0,
  amount: "1000000",
  slippage: 1
})
canix_compose_enter({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  opportunityId: "reti-staking-12",
  fromAssetId: 0,
  amount: "1000000",
  slippage: 1,
  paymentSignature: "<base64-json-payload>"
})

// Simulate compiled groups (no signing)
canix_simulate_execution({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  groups: [{ shapeKey: "mainnet:reti:v1:stake:algo", encodedTransactions: ["<base64-unsigned-txn>"] }]
})
canix_simulate_execution({
  address: "YOUR_ALGORAND_ADDRESS",  // pragma: allowlist secret
  groups: [{ shapeKey: "mainnet:reti:v1:stake:algo", encodedTransactions: ["<base64-unsigned-txn>"] }],
  paymentSignature: "<base64-json-payload>"
})

// Policy-as-a-service (plan or quotes[] + operator policy)
canix_validate_policy({
  policy: {
    schemaVersion: "1.0.0",
    maxProtocolWeightBps: 4000,
    minAlgoReserveMicroAlgos: "1000000",
    minTvlUsd: 25000,
    maxSourceAgeSeconds: 86400,
    noNewBorrows: true,
    executionReadyOnly: true
  },
  quotes: [{
    shapeKey: "mainnet:reti:v1:stake:algo",
    protocol: "reti",
    opportunityId: "reti-staking-12",
    weightBps: 4000,
    allocatedAmount: "1000000",
    allocatedAssetId: 0,
    tvlUsd: 1000000,
    sourceTimestamp: "2026-08-28T11:00:00.000Z",
    executionReady: true
  }],
  walletAlgoMicroAlgos: "5000000"
})
canix_validate_policy({
  policy: { schemaVersion: "1.0.0", noNewBorrows: true, executionReadyOnly: true },
  quotes: [{ shapeKey: "mainnet:reti:v1:stake:algo", protocol: "reti", executionReady: true }],
  paymentSignature: "<base64-json-payload>"
})

// Execution quotes (batch)
canix_get_execution_quote({
  quotes: [{
    shapeKey: "mainnet:tinyman:v2:addLiquidity:flexible",
    input: {
      userAddress: "YOUR_ALGORAND_ADDRESS",
      assetAId: 0,
      assetAAmount: "1000000",
      assetBId: 31566704,
      assetBAmount: "1000000",
      maxSlippageBps: 50
    }
  }]
})
canix_get_execution_quote({
  quotes: [/* same body */],
  paymentSignature: "<base64-json-payload>"
})

Verify the deployment

curl -s https://canix402-mcp.compx.io/health | jq

curl -s https://canix402-mcp.compx.io/.well-known/mcp | jq

/.well-known/mcp should return transport: "streamable-http" and url pointing at https://canix402-mcp.compx.io/mcp.

Client setup

Point your MCP client at the remote endpoint. No local npm package or stdio process is required for production use.

Cursor / Claude Desktop (URL transport)

{
  "mcpServers": {
    "canix402": {
      "url": "https://canix402-mcp.compx.io/mcp"
    }
  }
}

See also the x402 page for payment context when using paid tools.

Paid tool flow

Call a paid tool (e.g. canix_list_opportunities) without paymentSignature.
The tool returns PAYMENT_REQUIRED metadata with gateway payment requirements (same x402 policy as direct HTTP).
Your agent builds a PAYMENT-SIGNATURE payload client-side and retries the same tool with paymentSignature set.
On success, the tool returns the gateway response.

This mirrors the direct HTTP flow documented on x402 payment flow and quickstart.

Available tools

Tool names match discovery mcpServer.tools.

The same tools are also registered in-page on /webmcp via the WebMCP imperative API.

canix_health
canix_get_metadata
canix_get_discovery
canix_get_openapi
canix_get_token_prices
canix_list_execution_shapes
canix_list_opportunities
canix_search_opportunities
canix_get_personalized_opportunities
canix_get_opportunity_history
canix_check_eligibility
canix_get_plan
canix_get_rebalance_plan
canix_validate_policy
canix_compose_enter
canix_get_protocol_opportunities
canix_get_positions
canix_list_claimable
canix_get_execution_quote
canix_simulate_execution
canix_create_session
canix_refresh_session
canix_get_session
canix_create_watch
canix_refresh_watch
canix_get_watch
canix_rotate_watch_secret
canix_get_quote
canix_optin
canix_swap

Free tools include health, metadata, discovery, OpenAPI, execution shapes, swap quotes, and opt-ins. Paid tools include opportunities, positions, claimable rewards, execution quotes, and swap transactions.

MCP vs direct HTTP

MCP — best for agent hosts (Cursor, Claude Desktop) that speak MCP; typed tools and structured payment-retry hints.
Direct HTTP — best for custom integrations; use the gateway with discovery/OpenAPI and manual x402 headers.

Both paths hit the same public Caddy gateway for paid data. The MCP Worker is a thin pass-through and does not call a private upstream API.