# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zircuit.com/infra/gud-trading-engine-beta/api-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.