API Endpoint

Core Endpoints

Base URL

https://trading.ai.zircuit.com/api/engine/v1

Authentication

All API requests require authentication using a Bearer token.

Authorization: Bearer API_KEY

ⓘ Info

Contact the team to get the API_KEY, these are also shared in hackathons!

Methods

1. Get Trade Estimate

Get a quote and all necessary data to execute a trade directly from a user's wallet, or make your user sign it and use your own relayer to provide gasless experience.

POST /order/estimate

Request Body

For example, a trade of 1 USDC from Base to USDT in Optimism:

{
  "srcChainId": 8453,
  "srcToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "srcAmountWei": "1000000",
  "destChainId": 10,
  "destToken": "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58",
  "slippageBps": "100",
  "userAccount": "0x...",
  "destReceiver": "0x...",
  "feeRecipient": "0x...",
  "feeBps": "100"
}

ⓘ Info

Use this special addresses for native tokens: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE

Parameters

Parameter	Type	Required	Description
srcChainId	number	Yes	Source chain ID
srcToken	string	Yes	Source token contract address
srcAmountWei	string	Yes	Amount in wei (string to handle large numbers)
destChainId	number	Yes	Destination chain ID
destToken	string	Yes	Destination token contract address
slippageBps	number	Yes	Slippage tolerance over the estimated output token amount
userAccount	string	Yes	User's wallet address
destReceiver	string	Yes	Recipient address on destination chain
feeRecipient	string	No	Fee recipient address on SOURCE chain
feeBps	string	No	Fee percentage over the input token amount

Example response

{
  "message": "Trade estimate determined",
  "data": {
    "trade": {
      "tradeId": "0x1234...abcd",
      "nonce": "1",
      "userAccount": "0x1234567890123456789012345678901234567890",
      "destReceiver": "0x1234567890123456789012345678901234567890",
      "srcToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "srcTokenAmount": "1000000000",
      "srcChainId": 8453,
      "destToken": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
      "destTokenAmount": "995000000",
      "destTokenMinAmount": "993000000",
      "destChainId": 10,
      "adapter": "0xAdapterAddress",
      "protocolNativeFee": "0",
      "data": "0x...",
      "deadline": 1699127056,
      "fees": [
        {
          "bps": 100,
          "recipient": "0x1234567890123456789012345678901234567890"
        },
        {
          "bps": 25,
          "recipient": "0xprotocol_fee_recipient"
        }
      ],
      "guardianSignature": "0xabcde...",
      "eip712": {
        "types": {
          "EIP712Domain": [...],
          "Fee": [...],
          "Trade": [...]
        },
        "domain": {
          "name": "GudEngine",
          "version": "1.0.0",
          "chainId": 8453,
          "verifyingContract": "0xGudEngineAddress"
        },
        "message": {
          "tradeId": "0x1234...abcd",
          "nonce": 1,
          "userAccount": "0x1234567890123456789012345678901234567890",
          "destReceiver": "0x0x0000000000000000000000001234567890123456789012345678901234567890",
          "srcToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "srcTokenAmount": "1000000000",
          "srcChainId": 8453,
          "destToken": "0x0x0000000000000000000000007F5c764cBc14f9669B88837ca1490cCa17c31607",
          "destTokenMinAmount": "993000000",
          "destChainId": 10,
          "adapter": "0xAdapterAddress",
          "protocolNativeFee": "0",
          "data": "0x...",
          "deadline": 1699127056,
          "fees": [...],
          "guardianSignature": "0xabcde..."
        },
        "primaryType": "Trade"
      }
    },
    "tx": {
      "chainId": 8453,
      "data": "0x1234abcd...", // Encoded calldata for GudEngine.execute()
      "from": "0x1234567890123456789012345678901234567890",
      "to": "0xGudEngineContractAddress",
      "value": "0" // ETH value to send (usually 0 for ERC20)
    }
  }
}

Fee Structure

Integrator Fees

You can specify optional custom fees for your integration. The user will be charged a percentage of input tokens:

• feeRecipient: Your fee recipient address in source chain

• feeBps: Fee percentage in basis points (1 BPS = 0.01%, 10000 BPS = 100%)

feeRecipient will receive the fees in the same transaction.

Protocol Fees

The protocol supports adding a fee to support the infrastructure. It is not enabled at the moment.