> For the complete documentation index, see [llms.txt](https://docs.zircuit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zircuit.com/infra/gud-trading-engine-beta/api-endpoint.md).
# 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
```
> **ⓘ 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.
```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"
}
```
> **ⓘ 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**
```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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.zircuit.com/infra/gud-trading-engine-beta/api-endpoint.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.