> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tedprotocol.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API endpoints for TED Protocol

TED Protocol provides a REST API for querying configuration, getting swap quotes, building transactions, and executing gasless relayed transactions.

### Base URL

```
https://api.talken.io/api/v1
```

### Response Format

All responses follow a common wrapper structure:

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

On error:

```json theme={null}
{
  "success": false,
  "error": "Error message description"
}
```

***

## Configuration

Endpoints for retrieving supported chains, DEXs, tokens, and contract addresses.

### Get Chains

Returns the list of supported blockchain networks.

```
GET /config/chains
```

**Parameters:** None

**Response Fields:**

| Field            | Type   | Description                                               |
| ---------------- | ------ | --------------------------------------------------------- |
| `chainKey`       | string | Unique chain identifier (e.g. `"ethereum"`, `"arbitrum"`) |
| `chainId`        | number | EVM chain ID                                              |
| `name`           | string | Display name                                              |
| `rpcUrl`         | string | RPC endpoint URL                                          |
| `explorerUrl`    | string | Block explorer URL                                        |
| `nativeCurrency` | object | Native token info (`name`, `symbol`, `decimals`)          |

**Example:**

```bash theme={null}
curl https://api.talken.io/api/v1/config/chains
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "chainKey": "ethereum",
      "chainId": 1,
      "name": "Ethereum",
      "rpcUrl": "https://...",
      "explorerUrl": "https://etherscan.io",
      "nativeCurrency": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      }
    },
    {
      "chainKey": "arbitrum",
      "chainId": 42161,
      "name": "Arbitrum One",
      "rpcUrl": "https://...",
      "explorerUrl": "https://arbiscan.io",
      "nativeCurrency": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      }
    }
  ]
}
```

***

### Get DEXs

Returns available DEXs for a specific chain.

```
GET /config/dexs/{chainKey}
```

**Path Parameters:**

| Parameter  | Type   | Description                                        |
| ---------- | ------ | -------------------------------------------------- |
| `chainKey` | string | Chain identifier (e.g. `"ethereum"`, `"arbitrum"`) |

**Response Fields:**

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| `dexKey`        | string | Unique DEX identifier                     |
| `name`          | string | Display name                              |
| `routerAddress` | string | DEX router contract address               |
| `type`          | string | DEX type (e.g. `"uniswap_v3"`, `"curve"`) |

**Example:**

```bash theme={null}
curl https://api.talken.io/api/v1/config/dexs/ethereum
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "dexKey": "uniswap_v3",
      "name": "Uniswap V3",
      "routerAddress": "0x...",
      "type": "uniswap_v3"
    },
    {
      "dexKey": "curve",
      "name": "Curve Finance",
      "routerAddress": "0x...",
      "type": "curve"
    }
  ]
}
```

***

### Get Tokens

Returns supported tokens for a specific chain, including their capabilities (swap, bridge, etc.).

```
GET /config/tokens/{chainKey}
```

**Path Parameters:**

| Parameter  | Type   | Description      |
| ---------- | ------ | ---------------- |
| `chainKey` | string | Chain identifier |

**Response Fields:**

| Field          | Type      | Description                                                    |
| -------------- | --------- | -------------------------------------------------------------- |
| `symbol`       | string    | Token symbol (e.g. `"USDT"`, `"USDC"`)                         |
| `name`         | string    | Token full name                                                |
| `address`      | string    | Token contract address                                         |
| `decimals`     | number    | Token decimals                                                 |
| `capabilities` | string\[] | Supported operations: `"swap"`, `"bridge_lz"`, `"bridge_cctp"` |

**Example:**

```bash theme={null}
curl https://api.talken.io/api/v1/config/tokens/arbitrum
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "symbol": "USDT",
      "name": "Tether USD",
      "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
      "decimals": 6,
      "capabilities": ["swap", "bridge_lz"]
    },
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "decimals": 6,
      "capabilities": ["swap", "bridge_cctp"]
    },
    {
      "symbol": "TEDP",
      "name": "TED Protocol",
      "address": "0x...",
      "decimals": 18,
      "capabilities": ["bridge_lz"]
    }
  ]
}
```

***

### Get Contracts

Returns protocol contract addresses for a specific chain.

```
GET /config/contracts/{chainKey}
```

**Path Parameters:**

| Parameter  | Type   | Description      |
| ---------- | ------ | ---------------- |
| `chainKey` | string | Chain identifier |

**Response Fields:**

| Field     | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `diamond` | string | Main Diamond proxy contract address |
| `tedp`    | string | TEDP token contract address         |
| `relayer` | string | Gasless relayer contract address    |

**Example:**

```bash theme={null}
curl https://api.talken.io/api/v1/config/contracts/arbitrum
```

```json theme={null}
{
  "success": true,
  "data": {
    "diamond": "0x...",
    "tedp": "0x...",
    "relayer": "0x..."
  }
}
```

***

## Quote

### Get Quote

Returns a multi-path swap quote with optimal routing across available DEXs.

```
POST /quote
```

**Request Body:**

| Field         | Type   | Required    | Description                                  |
| ------------- | ------ | ----------- | -------------------------------------------- |
| `chainKey`    | string | Conditional | Chain identifier for same-chain swaps        |
| `srcChainKey` | string | Conditional | Source chain identifier for cross-chain      |
| `dstChainKey` | string | Conditional | Destination chain identifier for cross-chain |
| `tokenIn`     | string | Yes         | Input token symbol or address                |
| `tokenOut`    | string | Yes         | Output token symbol or address               |
| `amountIn`    | string | Yes         | Input amount (in token's smallest unit)      |
| `sender`      | string | No          | Sender wallet address                        |
| `recipient`   | string | No          | Recipient wallet address                     |

**Response Fields:**

| Field               | Type      | Description                                             |
| ------------------- | --------- | ------------------------------------------------------- |
| `amountOut`         | string    | Expected output amount                                  |
| `route`             | object\[] | Swap route steps                                        |
| `route[].dex`       | string    | DEX used for this step                                  |
| `route[].tokenIn`   | string    | Input token for this step                               |
| `route[].tokenOut`  | string    | Output token for this step                              |
| `route[].amountIn`  | string    | Input amount for this step                              |
| `route[].amountOut` | string    | Output amount for this step                             |
| `priceImpact`       | string    | Price impact in basis points                            |
| `bridgeType`        | string    | Bridge type if cross-chain: `"lz"`, `"cctp"`, or `null` |
| `estimatedGas`      | string    | Estimated gas cost                                      |

**Example — Same-chain swap:**

```bash theme={null}
curl -X POST https://api.talken.io/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{
    "chainKey": "arbitrum",
    "tokenIn": "USDT",
    "tokenOut": "USDC",
    "amountIn": "1000000000"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "amountOut": "999500000",
    "route": [
      {
        "dex": "uniswap_v3",
        "tokenIn": "USDT",
        "tokenOut": "USDC",
        "amountIn": "1000000000",
        "amountOut": "999500000"
      }
    ],
    "priceImpact": "5",
    "bridgeType": null,
    "estimatedGas": "180000"
  }
}
```

**Example — Cross-chain swap:**

```bash theme={null}
curl -X POST https://api.talken.io/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{
    "srcChainKey": "ethereum",
    "dstChainKey": "arbitrum",
    "tokenIn": "USDT",
    "tokenOut": "USDC",
    "amountIn": "1000000000"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "amountOut": "998800000",
    "route": [
      {
        "dex": "uniswap_v3",
        "tokenIn": "USDT",
        "tokenOut": "USDC",
        "amountIn": "1000000000",
        "amountOut": "999500000"
      },
      {
        "dex": "bridge_cctp",
        "tokenIn": "USDC",
        "tokenOut": "USDC",
        "amountIn": "999500000",
        "amountOut": "998800000"
      }
    ],
    "priceImpact": "5",
    "bridgeType": "cctp",
    "estimatedGas": "350000"
  }
}
```

***

## Transaction

### Build Transaction

Builds a ready-to-sign transaction based on the selected action type. The `action` field determines the transaction type and required parameters.

```
POST /tx/build
```

**Common Request Fields:**

| Field         | Type   | Required | Description                  |
| ------------- | ------ | -------- | ---------------------------- |
| `action`      | string | Yes      | Transaction type (see below) |
| `sender`      | string | Yes      | Sender wallet address        |
| `srcChainKey` | string | Yes      | Source chain identifier      |

**Action Types:**

| Action              | Description                         |
| ------------------- | ----------------------------------- |
| `swap`              | Single-chain single-hop swap        |
| `swapMultiHop`      | Single-chain multi-hop swap         |
| `bridgeOnlyLz`      | LayerZero bridge transfer (no swap) |
| `bridgeOnlyCctp`    | CCTP bridge transfer (no swap)      |
| `swapAndBridgeLz`   | Swap then bridge via LayerZero      |
| `swapAndBridgeCctp` | Swap then bridge via CCTP           |

**Additional Fields by Action:**

For **swap** and **swapMultiHop**:

| Field          | Type   | Required | Description               |
| -------------- | ------ | -------- | ------------------------- |
| `tokenIn`      | string | Yes      | Input token address       |
| `tokenOut`     | string | Yes      | Output token address      |
| `amountIn`     | string | Yes      | Input amount              |
| `minAmountOut` | string | Yes      | Minimum acceptable output |
| `deadline`     | number | Yes      | Unix timestamp deadline   |
| `dex`          | string | Yes      | DEX identifier to use     |

For **bridgeOnlyLz** and **bridgeOnlyCctp**:

| Field         | Type   | Required | Description                            |
| ------------- | ------ | -------- | -------------------------------------- |
| `token`       | string | Yes      | Token address to bridge                |
| `amount`      | string | Yes      | Amount to bridge                       |
| `dstChainKey` | string | Yes      | Destination chain identifier           |
| `recipient`   | string | Yes      | Recipient address on destination chain |

For **swapAndBridgeLz** and **swapAndBridgeCctp**:

| Field          | Type   | Required | Description                  |
| -------------- | ------ | -------- | ---------------------------- |
| `tokenIn`      | string | Yes      | Input token address          |
| `tokenOut`     | string | Yes      | Output token address         |
| `amountIn`     | string | Yes      | Input amount                 |
| `minAmountOut` | string | Yes      | Minimum acceptable output    |
| `dstChainKey`  | string | Yes      | Destination chain identifier |
| `recipient`    | string | Yes      | Recipient address            |
| `deadline`     | number | Yes      | Unix timestamp deadline      |
| `dex`          | string | Yes      | DEX identifier               |

**Response Fields:**

| Field      | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `to`       | string | Target contract address          |
| `data`     | string | Encoded calldata                 |
| `value`    | string | Native token value to send (wei) |
| `chainId`  | number | Chain ID for the transaction     |
| `gasLimit` | string | Recommended gas limit            |

**Example — Single-chain swap:**

```bash theme={null}
curl -X POST https://api.talken.io/api/v1/tx/build \
  -H "Content-Type: application/json" \
  -d '{
    "action": "swap",
    "sender": "0xYourAddress",
    "srcChainKey": "arbitrum",
    "tokenIn": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "tokenOut": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "amountIn": "1000000000",
    "minAmountOut": "995000000",
    "deadline": 1740000000,
    "dex": "uniswap_v3"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "to": "0xDiamondContractAddress",
    "data": "0x...",
    "value": "0",
    "chainId": 42161,
    "gasLimit": "250000"
  }
}
```

**Example — Cross-chain swap and bridge:**

```javascript theme={null}
const response = await fetch("https://api.talken.io/api/v1/tx/build", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "swapAndBridgeCctp",
    sender: walletAddress,
    srcChainKey: "ethereum",
    tokenIn: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    amountIn: "1000000000",
    minAmountOut: "995000000",
    dstChainKey: "arbitrum",
    recipient: walletAddress,
    deadline: Math.floor(Date.now() / 1000) + 3600,
    dex: "uniswap_v3"
  })
});

const { data: txData } = await response.json();

// Send the transaction with your wallet
const tx = await signer.sendTransaction({
  to: txData.to,
  data: txData.data,
  value: txData.value,
  gasLimit: txData.gasLimit
});

await tx.wait();
```

***

## Relayer (Gasless)

Endpoints for gasless transaction execution. Users sign the transaction, and the relayer submits it on-chain, paying the gas fee.

### Estimate Relayer Fee

Returns the estimated relayer fee for a gasless transaction.

```
POST /relayer/estimate-fee
```

**Request Body:**

| Field      | Type   | Required | Description                                     |
| ---------- | ------ | -------- | ----------------------------------------------- |
| `chainKey` | string | Yes      | Chain where the transaction will execute        |
| `action`   | string | Yes      | Transaction action type (same as `/tx/build`)   |
| `gasLimit` | string | No       | Estimated gas limit (auto-estimated if omitted) |

**Response Fields:**

| Field        | Type   | Description                                       |
| ------------ | ------ | ------------------------------------------------- |
| `feeToken`   | string | Token used for fee payment (e.g. `"USDT"`)        |
| `feeAmount`  | string | Fee amount in fee token's smallest unit           |
| `feeUsd`     | string | Fee in USD equivalent                             |
| `gasPrice`   | string | Current gas price (wei)                           |
| `validUntil` | number | Unix timestamp until which this estimate is valid |

**Example:**

```bash theme={null}
curl -X POST https://api.talken.io/api/v1/relayer/estimate-fee \
  -H "Content-Type: application/json" \
  -d '{
    "chainKey": "arbitrum",
    "action": "swap",
    "gasLimit": "250000"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "feeToken": "USDT",
    "feeAmount": "50000",
    "feeUsd": "0.05",
    "gasPrice": "100000000",
    "validUntil": 1740000600
  }
}
```

***

### Execute Relay Transaction

Submits a signed transaction for gasless execution via the relayer.

```
POST /tx/relay-execute
```

**Request Body:**

| Field                | Type   | Required | Description                  |
| -------------------- | ------ | -------- | ---------------------------- |
| `chainKey`           | string | Yes      | Chain identifier             |
| `signedTx`           | object | Yes      | Signed transaction data      |
| `signedTx.to`        | string | Yes      | Target contract address      |
| `signedTx.data`      | string | Yes      | Encoded calldata             |
| `signedTx.value`     | string | Yes      | Native token value           |
| `signedTx.signature` | string | Yes      | EIP-712 typed data signature |
| `strategy`           | string | Yes      | Relay strategy (see below)   |
| `feeToken`           | string | No       | Token for fee deduction      |

**Strategy Types:**

| Strategy               | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `eip7702-only`         | Execute via EIP-7702 Account Abstraction only   |
| `eip7702-first`        | Try EIP-7702 first, fall back to generic relay  |
| `generic`              | Gasless execution via generic relayer           |
| `generic-sponsored-lz` | Relay with sponsored LayerZero cross-chain fees |

**Response Fields:**

| Field         | Type   | Description                                              |
| ------------- | ------ | -------------------------------------------------------- |
| `txHash`      | string | On-chain transaction hash                                |
| `status`      | string | `"submitted"`, `"pending"`, `"confirmed"`, or `"failed"` |
| `blockNumber` | number | Block number (if confirmed)                              |
| `gasUsed`     | string | Actual gas used (if confirmed)                           |
| `feeDeducted` | string | Fee deducted from output (if applicable)                 |

**Example — Generic relay:**

```bash theme={null}
curl -X POST https://api.talken.io/api/v1/tx/relay-execute \
  -H "Content-Type: application/json" \
  -d '{
    "chainKey": "arbitrum",
    "signedTx": {
      "to": "0xDiamondContractAddress",
      "data": "0x...",
      "value": "0",
      "signature": "0x..."
    },
    "strategy": "generic"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "txHash": "0xabc123...",
    "status": "confirmed",
    "blockNumber": 185000000,
    "gasUsed": "210000"
  }
}
```

**Example — Gasless relay (JavaScript):**

```javascript theme={null}
// 1. Build the transaction
const buildRes = await fetch("https://api.talken.io/api/v1/tx/build", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "swap",
    sender: walletAddress,
    srcChainKey: "arbitrum",
    tokenIn: USDT_ADDRESS,
    tokenOut: USDC_ADDRESS,
    amountIn: "1000000000",
    minAmountOut: "995000000",
    deadline: Math.floor(Date.now() / 1000) + 600,
    dex: "uniswap_v3"
  })
});
const { data: txData } = await buildRes.json();

// 2. Sign with EIP-712
const signature = await signer.signTypedData(domain, types, txData);

// 3. Submit via relayer
const relayRes = await fetch("https://api.talken.io/api/v1/tx/relay-execute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chainKey: "arbitrum",
    signedTx: {
      to: txData.to,
      data: txData.data,
      value: txData.value,
      signature: signature
    },
    strategy: "generic",
    feeToken: "USDT"
  })
});

const { data: result } = await relayRes.json();
console.log("Tx hash:", result.txHash);
```

***

## Error Handling

When a request fails, the response includes an error message:

```json theme={null}
{
  "success": false,
  "error": "Invalid token address"
}
```

**Common Error Responses:**

| HTTP Status | Error                      | Description                                    |
| ----------- | -------------------------- | ---------------------------------------------- |
| 400         | `"Invalid chain key"`      | The specified chain is not supported           |
| 400         | `"Invalid token address"`  | Token address not found on the specified chain |
| 400         | `"Insufficient liquidity"` | Not enough liquidity for the requested swap    |
| 400         | `"Amount too small"`       | Input amount is below the minimum threshold    |
| 400         | `"Invalid action"`         | Unsupported action type for `/tx/build`        |
| 404         | `"Route not found"`        | No swap route available for the token pair     |
| 500         | `"Internal server error"`  | Server-side error — retry later                |
| 503         | `"Service unavailable"`    | API temporarily unavailable                    |