> ## 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 레퍼런스

> TED Protocol REST API 엔드포인트

TED Protocol은 설정 조회, 스왑 견적, 트랜잭션 빌드, 가스리스 릴레이 실행을 위한 REST API를 제공합니다.

### Base URL

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

### 응답 형식

모든 응답은 공통 래퍼 구조를 따릅니다:

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

에러 시:

```json theme={null}
{
  "success": false,
  "error": "에러 메시지 설명"
}
```

***

## 설정 (Configuration)

지원 체인, DEX, 토큰, 컨트랙트 주소를 조회하는 엔드포인트입니다.

### 체인 목록 조회

지원되는 블록체인 네트워크 목록을 반환합니다.

```
GET /config/chains
```

**파라미터:** 없음

**응답 필드:**

| 필드               | 타입     | 설명                                        |
| ---------------- | ------ | ----------------------------------------- |
| `chainKey`       | string | 고유 체인 식별자 (예: `"ethereum"`, `"arbitrum"`) |
| `chainId`        | number | EVM 체인 ID                                 |
| `name`           | string | 표시 이름                                     |
| `rpcUrl`         | string | RPC 엔드포인트 URL                             |
| `explorerUrl`    | string | 블록 익스플로러 URL                              |
| `nativeCurrency` | object | 네이티브 토큰 정보 (`name`, `symbol`, `decimals`) |

**예시:**

```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
      }
    }
  ]
}
```

***

### DEX 목록 조회

특정 체인에서 사용 가능한 DEX 목록을 반환합니다.

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

**경로 파라미터:**

| 파라미터       | 타입     | 설명                                     |
| ---------- | ------ | -------------------------------------- |
| `chainKey` | string | 체인 식별자 (예: `"ethereum"`, `"arbitrum"`) |

**응답 필드:**

| 필드              | 타입     | 설명                                    |
| --------------- | ------ | ------------------------------------- |
| `dexKey`        | string | 고유 DEX 식별자                            |
| `name`          | string | 표시 이름                                 |
| `routerAddress` | string | DEX 라우터 컨트랙트 주소                       |
| `type`          | string | DEX 유형 (예: `"uniswap_v3"`, `"curve"`) |

**예시:**

```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 /config/tokens/{chainKey}
```

**경로 파라미터:**

| 파라미터       | 타입     | 설명     |
| ---------- | ------ | ------ |
| `chainKey` | string | 체인 식별자 |

**응답 필드:**

| 필드             | 타입        | 설명                                              |
| -------------- | --------- | ----------------------------------------------- |
| `symbol`       | string    | 토큰 심볼 (예: `"USDT"`, `"USDC"`)                   |
| `name`         | string    | 토큰 전체 이름                                        |
| `address`      | string    | 토큰 컨트랙트 주소                                      |
| `decimals`     | number    | 토큰 소수점 자릿수                                      |
| `capabilities` | string\[] | 지원 기능: `"swap"`, `"bridge_lz"`, `"bridge_cctp"` |

**예시:**

```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 /config/contracts/{chainKey}
```

**경로 파라미터:**

| 파라미터       | 타입     | 설명     |
| ---------- | ------ | ------ |
| `chainKey` | string | 체인 식별자 |

**응답 필드:**

| 필드        | 타입     | 설명                     |
| --------- | ------ | ---------------------- |
| `diamond` | string | 메인 Diamond 프록시 컨트랙트 주소 |
| `tedp`    | string | TEDP 토큰 컨트랙트 주소        |
| `relayer` | string | 가스리스 릴레이어 컨트랙트 주소      |

**예시:**

```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)

### 스왑 견적 조회

사용 가능한 DEX에서 최적 라우팅을 적용한 멀티패스 스왑 견적을 반환합니다.

```
POST /quote
```

**요청 본문:**

| 필드            | 타입     | 필수  | 설명                |
| ------------- | ------ | --- | ----------------- |
| `chainKey`    | string | 조건부 | 동일 체인 스왑 시 체인 식별자 |
| `srcChainKey` | string | 조건부 | 크로스체인 시 소스 체인 식별자 |
| `dstChainKey` | string | 조건부 | 크로스체인 시 대상 체인 식별자 |
| `tokenIn`     | string | Yes | 입력 토큰 심볼 또는 주소    |
| `tokenOut`    | string | Yes | 출력 토큰 심볼 또는 주소    |
| `amountIn`    | string | Yes | 입력 금액 (토큰 최소 단위)  |
| `sender`      | string | No  | 발신자 지갑 주소         |
| `recipient`   | string | No  | 수신자 지갑 주소         |

**응답 필드:**

| 필드                  | 타입        | 설명                                          |
| ------------------- | --------- | ------------------------------------------- |
| `amountOut`         | string    | 예상 출력 금액                                    |
| `route`             | object\[] | 스왑 라우트 단계                                   |
| `route[].dex`       | string    | 해당 단계에서 사용된 DEX                             |
| `route[].tokenIn`   | string    | 해당 단계의 입력 토큰                                |
| `route[].tokenOut`  | string    | 해당 단계의 출력 토큰                                |
| `route[].amountIn`  | string    | 해당 단계의 입력 금액                                |
| `route[].amountOut` | string    | 해당 단계의 출력 금액                                |
| `priceImpact`       | string    | 가격 영향 (basis points)                        |
| `bridgeType`        | string    | 크로스체인 시 브릿지 타입: `"lz"`, `"cctp"`, 또는 `null` |
| `estimatedGas`      | string    | 예상 가스 비용                                    |

**예시 — 동일 체인 스왑:**

```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"
  }
}
```

**예시 — 크로스체인 스왑:**

```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)

### 트랜잭션 빌드

선택한 액션 타입에 따라 서명 가능한 트랜잭션을 빌드합니다. `action` 필드가 트랜잭션 유형과 필요한 파라미터를 결정합니다.

```
POST /tx/build
```

**공통 요청 필드:**

| 필드            | 타입     | 필수  | 설명              |
| ------------- | ------ | --- | --------------- |
| `action`      | string | Yes | 트랜잭션 유형 (아래 참조) |
| `sender`      | string | Yes | 발신자 지갑 주소       |
| `srcChainKey` | string | Yes | 소스 체인 식별자       |

**액션 유형:**

| 액션                  | 설명                       |
| ------------------- | ------------------------ |
| `swap`              | 단일 체인 단일 홉 스왑            |
| `swapMultiHop`      | 단일 체인 멀티 홉 스왑            |
| `bridgeOnlyLz`      | LayerZero 브릿지 전송 (스왑 없음) |
| `bridgeOnlyCctp`    | CCTP 브릿지 전송 (스왑 없음)      |
| `swapAndBridgeLz`   | 스왑 후 LayerZero 브릿지       |
| `swapAndBridgeCctp` | 스왑 후 CCTP 브릿지            |

**액션별 추가 필드:**

**swap** 및 **swapMultiHop**:

| 필드             | 타입     | 필수  | 설명               |
| -------------- | ------ | --- | ---------------- |
| `tokenIn`      | string | Yes | 입력 토큰 주소         |
| `tokenOut`     | string | Yes | 출력 토큰 주소         |
| `amountIn`     | string | Yes | 입력 금액            |
| `minAmountOut` | string | Yes | 최소 허용 출력 금액      |
| `deadline`     | number | Yes | Unix 타임스탬프 마감 시간 |
| `dex`          | string | Yes | 사용할 DEX 식별자      |

**bridgeOnlyLz** 및 **bridgeOnlyCctp**:

| 필드            | 타입     | 필수  | 설명            |
| ------------- | ------ | --- | ------------- |
| `token`       | string | Yes | 브릿지할 토큰 주소    |
| `amount`      | string | Yes | 브릿지 금액        |
| `dstChainKey` | string | Yes | 대상 체인 식별자     |
| `recipient`   | string | Yes | 대상 체인의 수신자 주소 |

**swapAndBridgeLz** 및 **swapAndBridgeCctp**:

| 필드             | 타입     | 필수  | 설명               |
| -------------- | ------ | --- | ---------------- |
| `tokenIn`      | string | Yes | 입력 토큰 주소         |
| `tokenOut`     | string | Yes | 출력 토큰 주소         |
| `amountIn`     | string | Yes | 입력 금액            |
| `minAmountOut` | string | Yes | 최소 허용 출력 금액      |
| `dstChainKey`  | string | Yes | 대상 체인 식별자        |
| `recipient`    | string | Yes | 수신자 주소           |
| `deadline`     | number | Yes | Unix 타임스탬프 마감 시간 |
| `dex`          | string | Yes | DEX 식별자          |

**응답 필드:**

| 필드         | 타입     | 설명                  |
| ---------- | ------ | ------------------- |
| `to`       | string | 대상 컨트랙트 주소          |
| `data`     | string | 인코딩된 calldata       |
| `value`    | string | 전송할 네이티브 토큰 값 (wei) |
| `chainId`  | number | 트랜잭션의 체인 ID         |
| `gasLimit` | string | 권장 가스 한도            |

**예시 — 단일 체인 스왑:**

```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"
  }
}
```

**예시 — 크로스체인 스왑 및 브릿지 (JavaScript):**

```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();

// 지갑으로 트랜잭션 전송
const tx = await signer.sendTransaction({
  to: txData.to,
  data: txData.data,
  value: txData.value,
  gasLimit: txData.gasLimit
});

await tx.wait();
```

***

## 릴레이어 (Gasless)

가스리스 트랜잭션 실행을 위한 엔드포인트입니다. 사용자가 트랜잭션에 서명하면, 릴레이어가 가스 수수료를 대납하여 온체인에 제출합니다.

### 릴레이어 수수료 추정

가스리스 트랜잭션의 예상 릴레이어 수수료를 반환합니다.

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

**요청 본문:**

| 필드         | 타입     | 필수  | 설명                           |
| ---------- | ------ | --- | ---------------------------- |
| `chainKey` | string | Yes | 트랜잭션이 실행될 체인                 |
| `action`   | string | Yes | 트랜잭션 액션 유형 (`/tx/build`와 동일) |
| `gasLimit` | string | No  | 예상 가스 한도 (미입력 시 자동 추정)       |

**응답 필드:**

| 필드           | 타입     | 설명                      |
| ------------ | ------ | ----------------------- |
| `feeToken`   | string | 수수료 결제 토큰 (예: `"USDT"`) |
| `feeAmount`  | string | 수수료 토큰 최소 단위로의 수수료 금액   |
| `feeUsd`     | string | USD 환산 수수료              |
| `gasPrice`   | string | 현재 가스 가격 (wei)          |
| `validUntil` | number | 견적 유효 기간 (Unix 타임스탬프)   |

**예시:**

```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
  }
}
```

***

### 릴레이 트랜잭션 실행

서명된 트랜잭션을 릴레이어를 통해 가스리스로 실행합니다.

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

**요청 본문:**

| 필드                   | 타입     | 필수  | 설명                |
| -------------------- | ------ | --- | ----------------- |
| `chainKey`           | string | Yes | 체인 식별자            |
| `signedTx`           | object | Yes | 서명된 트랜잭션 데이터      |
| `signedTx.to`        | string | Yes | 대상 컨트랙트 주소        |
| `signedTx.data`      | string | Yes | 인코딩된 calldata     |
| `signedTx.value`     | string | Yes | 네이티브 토큰 값         |
| `signedTx.signature` | string | Yes | EIP-712 타입 데이터 서명 |
| `strategy`           | string | Yes | 릴레이 전략 (아래 참조)    |
| `feeToken`           | string | No  | 수수료 차감 토큰         |

**전략 유형:**

| 전략                     | 설명                                 |
| ---------------------- | ---------------------------------- |
| `eip7702-only`         | EIP-7702 Account Abstraction으로만 실행 |
| `eip7702-first`        | EIP-7702 우선 시도, 실패 시 일반 릴레이로 폴백    |
| `generic`              | 일반 릴레이어를 통한 가스리스 실행                |
| `generic-sponsored-lz` | LayerZero 크로스체인 수수료가 스폰서되는 릴레이 실행  |

**응답 필드:**

| 필드            | 타입     | 설명                                                       |
| ------------- | ------ | -------------------------------------------------------- |
| `txHash`      | string | 온체인 트랜잭션 해시                                              |
| `status`      | string | `"submitted"`, `"pending"`, `"confirmed"`, 또는 `"failed"` |
| `blockNumber` | number | 블록 번호 (확인 시)                                             |
| `gasUsed`     | string | 실제 사용 가스 (확인 시)                                          |
| `feeDeducted` | string | 출력에서 차감된 수수료 (해당 시)                                      |

**예시 — 일반 릴레이:**

```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"
  }
}
```

**예시 — 가스리스 릴레이 (JavaScript):**

```javascript theme={null}
// 1. 트랜잭션 빌드
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. EIP-712 서명
const signature = await signer.signTypedData(domain, types, txData);

// 3. 릴레이어를 통해 제출
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);
```

***

## 에러 처리

요청 실패 시, 응답에 에러 메시지가 포함됩니다:

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

**주요 에러 응답:**

| HTTP 상태 | 에러                         | 설명                          |
| ------- | -------------------------- | --------------------------- |
| 400     | `"Invalid chain key"`      | 지정된 체인이 지원되지 않음             |
| 400     | `"Invalid token address"`  | 해당 체인에서 토큰 주소를 찾을 수 없음      |
| 400     | `"Insufficient liquidity"` | 요청한 스왑에 충분한 유동성이 없음         |
| 400     | `"Amount too small"`       | 입력 금액이 최소 기준 미만             |
| 400     | `"Invalid action"`         | `/tx/build`에서 지원하지 않는 액션 유형 |
| 404     | `"Route not found"`        | 해당 토큰 쌍에 대한 스왑 라우트 없음       |
| 500     | `"Internal server error"`  | 서버 내부 에러 — 나중에 재시도          |
| 503     | `"Service unavailable"`    | API 일시적으로 사용 불가             |