API 레퍼런스

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

Base URL

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

응답 형식

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

{
  "success": true,
  "data": { ... }
}

에러 시:

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

예시:

curl https://api.talken.io/api/v1/config/chains

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

예시:

curl https://api.talken.io/api/v1/config/dexs/ethereum

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

예시:

curl https://api.talken.io/api/v1/config/tokens/arbitrum

{
  "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	가스리스 릴레이어 컨트랙트 주소

예시:

curl https://api.talken.io/api/v1/config/contracts/arbitrum

{
  "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	예상 가스 비용

예시 — 동일 체인 스왑:

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

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

예시 — 크로스체인 스왑:

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

{
  "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	권장 가스 한도

예시 — 단일 체인 스왑:

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

{
  "success": true,
  "data": {
    "to": "0xDiamondContractAddress",
    "data": "0x...",
    "value": "0",
    "chainId": 42161,
    "gasLimit": "250000"
  }
}

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

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 타임스탬프)

예시:

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

{
  "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	출력에서 차감된 수수료 (해당 시)

예시 — 일반 릴레이:

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

{
  "success": true,
  "data": {
    "txHash": "0xabc123...",
    "status": "confirmed",
    "blockNumber": 185000000,
    "gasUsed": "210000"
  }
}

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

// 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);

에러 처리

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

{
  "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 일시적으로 사용 불가

개요

프로토콜

TEDP 토큰

리스크

보안

개발자

리소스

Base URL

응답 형식

설정 (Configuration)

체인 목록 조회

DEX 목록 조회

토큰 목록 조회

컨트랙트 주소 조회

견적 (Quote)

스왑 견적 조회

트랜잭션 (Transaction)

트랜잭션 빌드

릴레이어 (Gasless)

릴레이어 수수료 추정

릴레이 트랜잭션 실행

에러 처리

​Base URL

​응답 형식

​설정 (Configuration)

​체인 목록 조회

​DEX 목록 조회

​토큰 목록 조회

​컨트랙트 주소 조회

​견적 (Quote)

​스왑 견적 조회

​트랜잭션 (Transaction)

​트랜잭션 빌드

​릴레이어 (Gasless)

​릴레이어 수수료 추정

​릴레이 트랜잭션 실행

​에러 처리

Base URL

응답 형식

설정 (Configuration)

체인 목록 조회

DEX 목록 조회

토큰 목록 조회

컨트랙트 주소 조회

견적 (Quote)

스왑 견적 조회

트랜잭션 (Transaction)

트랜잭션 빌드

릴레이어 (Gasless)

릴레이어 수수료 추정

릴레이 트랜잭션 실행

에러 처리