# API Endpoint

## Core Endpoints

### Base URL

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

### Authentication

All API requests require authentication using a Bearer token.

```bash
Authorization: Bearer API_KEY
```

> <mark style="color:blue;">**ⓘ Info**</mark>
>
> 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.

```http
POST /order/estimate
```

**Request Body**

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

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

> <mark style="color:blue;">**ⓘ Info**</mark>
>
> 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**

```json
{
  "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.