메인 콘텐츠로 건너뛰기

​
개요

  • 기본 경로: /api/v1
  • 인증: x-api-key 헤더의 API 키
  • 멱등성: 쓰기 작업은 Idempotency-Key 헤더(UUID) 필요
  • 응답 형식: 모든 응답에는 추적을 위한 x-request-id 헤더 포함

​
엔드포인트

  • GET /api/v1/wallets – 사용자 지갑 목록
  • GET /api/v1/wallets/balances – 호출자 지갑 잔액(체인별; 기본 지갑 사용)
  • GET /api/v1/wallets/:address/balances – 소유 지갑 주소 잔액
  • GET /api/v1/tx/:id – 트랜잭션 상세 조회
  • POST /api/v1/send – 네이티브/토큰 전송 (EVM + Solana)
  • POST /api/v1/token/approve – ERC20 토큰 승인 (EVM 전용)
  • POST /api/v1/contracts/send – 일반 컨트랙트 호출 (EVM 전용)
  • POST /api/v1/trade/quote – 스왑 견적 (EVM + Solana)
  • POST /api/v1/trade/swap – 스왑 실행 (EVM + Solana)

​
체인

지원 체인 전체 목록은 지원 체인에서 확인하세요. 요청의 chain 필드에는 슬러그(예: base, solana-devnet)를 사용합니다.

​
요청 제한

  • 쓰기(POST /api/v1/trade/quote 포함): 사용자당 분당 15 요청
  • 읽기: 사용자당 분당 60 요청
  • 응답: 초과 시 HTTP 429 반환
  • 헤더: Retry-After(다음 윈도우까지의 초)

​
멱등성(쓰기)

  • 모든 변경 엔드포인트는 Idempotency-Key가 필요합니다.
  • 동일한 본문으로 키를 재사용하면 원래 200 응답을 반환합니다.
  • 다른 본문으로 재사용하면 HTTP 409와 code: IDEMPOTENT_BODY_MISMATCH를 반환합니다.
  • 저장된 성공 응답 없이 재사용하면 HTTP 409와 code: IDEMPOTENT_REPLAY를 반환합니다.
  • 키는 인증된 사용자 범위이며, 엔드포인트 경로가 추적으로 기록됩니다.
  • 적용 대상: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

​
오류 처리

​
오류 응답 형식

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
오류 코드

  • UNAUTHORIZED – 인증 누락/무효 또는 API 키 오류 (HTTP 401)
  • FORBIDDEN – 인증되었으나 작업 권한 없음 (HTTP 403)
  • NOT_FOUND – 리소스를 찾을 수 없음 (HTTP 404)
  • RATE_LIMITED – 요청 제한 초과 (HTTP 429)
  • INVALID_INPUT – 잘못된 요청 파라미터 (HTTP 400)
  • WALLET_NOT_FOUND – 지정된 지갑을 찾을 수 없음
  • USER_NOT_LINKED – 사용자가 Privy에 연결되지 않음
  • WALLET_NOT_DELEGATED – 지갑이 서버 서명자에게 위임되지 않음
  • WALLET_ID_REQUIRED – Privy 지갑 ID 누락
  • CHAIN_UNKNOWN – 알 수 없거나 지원되지 않는 체인
  • INSUFFICIENT_FUNDS – 송신자의 자금 부족(가치/수수료)
  • IDEMPOTENT_BODY_MISMATCH – 동일한 멱등 키로 다른 요청 본문 (HTTP 409)
  • IDEMPOTENT_REPLAY – 멱등 키가 이미 사용됨 (HTTP 409)
  • PRIVY_RPC_ERROR – Privy RPC 서비스 오류
  • SEND_FAILED – 트랜잭션 제출 실패
  • SERVICE_UNAVAILABLE – 필요한 서비스가 구성되지 않음
  • QUOTE_FAILED – 견적 서비스 오류 (HTTP 400)
  • INTERNAL_ERROR – 서버 오류
QUOTE_FAILED 세부사항:
  • Solana/Jupiter: 일부 Solana mint는 Jupiter에서 거래할 수 없습니다(선별된 허용 목록). 이 경우 API는 HTTP 400과 code: QUOTE_FAILED, “Token not tradable on Jupiter”와 같은 오류 메시지를 반환합니다.
  • EVM/1inch: 토큰이 1inch에서 지원되지 않는 경우 API는 HTTP 400과 code: QUOTE_FAILED, “Token not tradable on 1inch”와 같은 메시지를 반환합니다.
  • 요청된 출력 토큰/mint가 업스트림 제공자에 의해 거래 불가로 표시된 경우 이는 예상된 동작이며, 다른 곳에 풀이 존재하더라도 발생합니다.

​
검증

​
주소 형식

  • EVM: /^0x[a-fA-F0-9]{40}$/ 정규식과 일치해야 합니다
  • Solana: 유효한 base58 공개키여야 합니다

​
공통 매개변수

  • 금액(EVM): 정수 문자열만 허용(10진수 또는 0x-hex). 음수가 될 수 없습니다. ERC20 및 value의 경우 uint256에 맞아야 합니다.
  • 금액(Solana): 기본 단위의 정수 문자열. SPL 금액은 부호 없는 64비트 범위 이내여야 합니다.
  • 송신자(from): 선택 사항. 생략 시 지정한 체인에 대해 사용자의 기본 지갑이 사용됩니다.
  • 멱등성: 모든 쓰기 엔드포인트는 Idempotency-Key 헤더가 필요합니다. 동일한 본문으로 반복하면 원래 응답을 반환합니다.

​
네이티브 토큰 키워드

거래 엔드포인트(/api/v1/trade/quote, /api/v1/trade/swap)는 fromToken/toToken에 대소문자를 구분하지 않는 NATIVE 키워드를 허용합니다:
  • EVM: NATIVE는 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE로 해석됩니다
  • Solana: NATIVE는 래핑된 SOL mint So11111111111111111111111111111111111111112로 해석됩니다
  • 응답은 해석된 주소를 반환합니다(NATIVE 아님)
  • 전송 엔드포인트는 네이티브 전송에 토큰 주소 대신 asset: "native"를 사용합니다

​
규약

  • 체인 선택: chain 슬러그를 사용합니다(예: base, base-sepolia, solana-devnet).
  • Solana Transaction.chainId 센티널 매핑: 0 = mainnet, -2 = testnet, -3 = devnet.
  • 멱등성: 사용자/키별로 고유합니다. 재전송은 원래 응답을 반환하며, 본문이 다르면 409를 반환합니다.

​
관련

지원 체인

정책 및 보안