Business API Request Models

Quote request

POST /api/v3/quotes

Required fields: fromCcy, toCcy, amount

Optional fields: direction (from/to, default from), type (fixed/float, default fixed), refundAddress, routeConstraints

{
  "fromCcy": "BTC",
  "toCcy": "ETH",
  "amount": "0.5",
  "direction": "from",
  "type": "fixed"
}

Onchain execution lifecycle

Discover routes with GET /api/v3/routes. If the selected card has executionType: "onchain", resolve it with POST /api/v3/onchain/routes/resolve, sign or broadcast the returned payload, report the result with POST /api/v3/onchain/executions, then poll GET /api/v3/onchain/executions/{executionPlanId}.

For route discovery, walletAddress remains the source signer or principal binding. Use recipientAddress as the destination recipient for cross-namespace onchain routes. Mayan discovery requires recipientAddress when the destination wallet namespace differs from the source signer namespace, such as an EVM signer with a Solana recipient.

GET https://mindswap.fun/api/v3/routes?fromCcy=ETH&toCcy=SOL&amount=0.5&direction=from&type=fixed&walletAddress=0x0000000000000000000000000000000000000001&walletChainNamespace=eip155&recipientAddress=So11111111111111111111111111111111111111112

Resolve and report are idempotent mutations. Report and status require X-Onchain-Execution-Access-Token, using the executionAccessToken returned by resolve.

Resolve onchain route

POST /api/v3/onchain/routes/resolve

Required: routeQuoteId, walletAddress

Optional: walletChainNamespace (eip155 or solana), slippageBps

{
  "routeQuoteId": "rqq_0123456789abcdef0123456789abcdef0123456789abcdef",
  "walletAddress": "0x0000000000000000000000000000000000000001",
  "walletChainNamespace": "eip155",
  "slippageBps": 50
}

Report execution

POST /api/v3/onchain/executions

Required: executionPlanId, chainNamespace, walletAddress, and either txHash or signatures.

{
  "executionPlanId": "ocx_0123456789abcdef0123456789abcdef",
  "chainNamespace": "eip155",
  "walletAddress": "0x0000000000000000000000000000000000000001",
  "txHash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

{
  "executionPlanId": "ocx_0123456789abcdef0123456789abcdef",
  "chainNamespace": "eip155",
  "walletAddress": "0x0000000000000000000000000000000000000001",
  "signatures": [
    {
      "signatureId": "sig_1",
      "purpose": "permit",
      "signature": "0x..."
    }
  ]
}

Order creation request

POST /api/v3/orders

The business surface accepts either a createToken, or a full order input with fromCcy, toCcy, amount, and toAddress.

Note: Business order creation does not accept quoteId.

Supported fields:

• createToken
• fromCcy, toCcy, amount
• direction, type
• toAddress, tag
• refundAddress
• affiliateCode, email

Emergency action request

POST /api/v3/orders/{orderId}/emergency

• choice: EXCHANGE or REFUND
• refundAddress — required when choice is REFUND
• refundTag

Webhook requests

Create webhook

• url — destination URL
• events — array of event types
• description — optional

Supported events

• order.created
• order.awaiting_deposit
• order.exchange_started
• order.withdraw_started
• order.completed
• order.expired
• order.emergency
• order.updated
• order.failed

Replay request

• eventId, or since / until time window
• Optional limit up to 100