개요#

Catapult API는 합성 토큰 파생상품 플랫폼(거래 및 토큰 데이터)을 요청/응답 작업을 위한 단일 GraphQL 엔드포인트와 실시간 구독을 위한 WebSocket 엔드포인트를 통해 제공합니다.

기본 엔드포인트#

모든 HTTP 요청은 POST를 사용하며 { "query": "...", "variables": { ... } } 형태의 JSON 본문을 보냅니다.

인증#

인증이 필요한 작업은 Authorization 헤더로 전송하는 JWT 베어러 토큰을 사용합니다:

Authorization: Bearer <your-jwt-token>

토큰은 JSON Web Token(JWT)이며 기본적으로 발급 시점부터 730일(약 2년) 유효합니다 — 만료 전에 교체하세요. 공개되는 것은 ping뿐이며, 나머지 모든 작업에는 베어러 토큰이 필요 합니다. 또한 tokens, turboToken 같은 읽기 작업에는 tokens.read 권한이 필요합니다.

API 키 생성#

catapult.trade/settings/api-key(Settings → API Key)의 계정 대시보드에서 토큰을 생성하세요. 계정은 catapult.trade에서 관리할 수 있습니다.

규칙#

• ID는 불투명한 문자열입니다; 파싱하지 마세요.
• 금액은 String! 타입의 문자열로 인코딩된 정수입니다(예: balanceUsdtDrops) — float가 아니라 BigInt로 파싱하세요. 사용자 정의 스칼라는 DateTime뿐입니다.
• 타임스탬프는 DateTime 스칼라(ISO-8601, UTC)를 사용합니다.
• 리스트 쿼리는 input.pagination을 통한 커서 페이지네이션을 사용합니다: limit(기본 10)과 afterCursor / beforeCursor.

빠른 예시#

query Tokens {
  # 전체 PublicTokenListInput과 토큰 필드는 Reference 탭 참조
  tokens(input: { pagination: { limit: 5 } }) {
    items { id }
  }
}

API 키 OAuth#

이 링크를 사용하면 카피 트레이딩 등 다양한 기능을 만들기 위해 사용자의 API 키를 받을 수 있습니다. 사용자가 자신의 API 키에 권한을 부여하면, 해당 키가 화이트리스트에 등록된 콜백 URL로 전달됩니다.

https://catapult.trade/settings/api-key?bot_id=<WHITELISTED_BOT_ID>

<WHITELISTED_BOT_ID>를 화이트리스트에 등록된 봇의 ID로 바꾸세요.

봇 화이트리스트 등록#

개발팀에 연락하여 봇을 화이트리스트에 등록하세요:

[email protected]

단위 및 규칙#

먼저 읽어 주세요 — API의 모든 금액 필드는 이 규칙에 의존합니다.

USDT drops (*UsdtDrops)#

모든 USDT 금액은 USDT × 1,000,000(소수점 6자리)의 정수이며 UsdtDrops 접미사가 붙습니다. 이들은 String!(문자열로 인코딩된 정수)로 전송됩니다 — float가 아니라 BigInt로 파싱하세요.

변환: usdt = drops / 1e6, drops = round(usdt × 1e6) — BigInt로 계산하세요.

레버리지 (leverageX10)#

레버리지는 레버리지 × 10으로 인코딩됩니다. leverageX10: 125는 12.5×, 30은 **3×**를 의미합니다.

증거금 vs 명목#

notional = collateral × leverage. 당신이 넣는 금액이 증거금(collateral), 포지션의 USDT 액면가가 **명목(notional)**입니다.

포지션을 열 때 금액은 수수료 차감 전 증거금입니다. tradeOpen은 usdtDrops (USDT 기준) 또는 amountWei(토큰 기준) 중 정확히 하나를 받으며, 엔진이 그것과 레버리지로 명목을 산출합니다. 이는 명목이 아닙니다.

잔액#

userBalance { balanceUsdtDrops, inPositionsBalanceUsdtDrops }:

토큰 미디어 (fileId)#

토큰 이미지는 **fileId**를 tokenCreate에 전달하여 첨부합니다. 두 가지 방법이 있습니다:

1. 랜덤라이저 — tokenRandomizedPreset이 바로 사용할 수 있는 fileId(이름, 심볼, 모드 등 포함)를 반환하며, tokenCreate에 그대로 전달할 수 있습니다.
2. 직접 업로드 — 3단계 S3 presigned-POST 플로우:
   • fileUpload(input) → S3 presigned-POST URL과 클라이언트가 multipart POST에 포함해야 하는 폼 필드를 반환합니다.
   • 클라이언트는 그 정확한 폼 필드와 함께 해당 S3 URL로 이미지를 POST합니다.
   • fileFinalize(id) → S3 POST 성공 후 업로드 완료를 표시하고 공개 파일 URL을 반환합니다. 결과 파일을 토큰 이미지로 사용하세요.

업로드 제한: JPEG 또는 PNG만, 최대 5 MB, 최소 314×314 px. presigned POST는 fileUpload 호출 후 15초 이내에 완료되어야 하며, 업로드는 IP당 시간당 200회로 제한됩니다.

토큰 속도 모드#

모든 토큰은 다섯 가지 속도 모드 중 하나로 동작합니다. 생성/랜덤화 필드는 turboTokenMode이고, 토큰 레코드는 speedMode를 노출합니다. SLOW와 NORMAL은 같은 모드의 두 이름입니다.

아래 최대 레버리지와 수명 값은 서버에서 바뀔 수 있는 현재 구성입니다 — 현재 값으로 취급하고 라이브 leverage-config 쿼리로 확인하세요.

최대 레버리지는 고정된 엔진 상한#

각 모드의 최대 레버리지는 엔진이 적용하는 엄격한 상한입니다 — 표의 값을 직접 사용하세요. 엔진은 그 이상의 주문을 거부합니다.

수수료 및 포지션 크기#

개설 수수료(~1%)#

포지션을 열면 보내는 증거금에서 차감되는 약 1%의 개설 수수료 (0.01)가 부과됩니다:

collateral_post_fee = collateral_sent × (1 − fee)

잠기는 증거금이 정확히 notional / leverage가 되도록 하려면 다음을 보내세요:

collateral_sent = (notional / leverage) / (1 − fee)

포지션당 명목 상한#

서버에서 포지션당 명목 상한이 적용됩니다 — 현재 (토큰, 레버리지, 방향)당 20,000 USDT입니다. 초과하면 Maximum notional limit … exceeded가 반환됩니다. 정확한 값은 라이브 구성에서 확인하세요. 모드나 레버리지에 따라 다를 수 있습니다.

사용 가능한 최대 포지션(명목)#

fee = 0.01, free = balanceUsdtDrops / 1e6, inPos = inPositionsBalanceUsdtDrops / 1e6, capTotal = 선택적 자체 총 증거금 상한, capPos = 포지션당 명목 상한(~20,000), L = 레버리지라고 하면:

maxCollateralFromBalance = free × (1 − fee)
remainingTotalBudget     = capTotal − inPos          # 총 상한을 적용하는 경우
maxNewCollateral         = min(maxCollateralFromBalance, remainingTotalBudget)
maxNotionalAchievable    = maxNewCollateral × L
maxPositionNotional      = min(maxNotionalAchievable, capPos)

실제로 보낼 증거금 = (maxPositionNotional / L) / (1 − fee).

반올림 함정. (1 − fee)로 나눈 뒤 단순한 round(collateral × 1e6)은 상한을 몇 drops 초과하여 개설이 거부됩니다. 보내기 전에 증거금을 drops(BigInt) 단위의 작은 단계 (예: 10 drops = 0.00001 USDT)로 내림하세요. 1센트의 무시할 만한 일부만 잃고 어떤 레버리지에서도 상한 아래에 머뭅니다.

계산 예시#

FLASH, 3×, 수수료 1%, 명목 상한 20,000:

collateral_post_fee target = 20,000 / 3        = 6,666.67
collateral_sent            = 6,666.67 / 0.99 ≈ 6,734.01   (drops로 내림)
→ 수수료 차감 후 잠김 ≈ 6,666.67, 명목 ≈ 20,000

상태 코드#

GraphQL 응답은 작업이 실패해도 HTTP 200을 반환합니다 — errors[] 배열과 각 오류의 extensions.code를 확인하세요. 전송 계층 문제는 표준 HTTP 상태 코드를 사용합니다.

HTTP 상태 코드#

GraphQL 서비스는 인증·권한·레이트 리밋 실패를 응답 내에서 200으로 반환합니다(GraphQL 오류 코드 참조). 전송 계층의 401 / 403 / 429는 상위 게이트웨이/CDN이 API에 도달하기 전에 요청을 거부한 경우에만 발생합니다.

GraphQL 오류 코드#

코드는 대소문자를 구분합니다; 정확한 문자열로 일치시키세요. 도메인 코드는 PascalCase(예: RateLimited)이며, 일부 프레임워크 코드는 대문자 스네이크 케이스(예: UNAUTHENTICATED)입니다.

오류 형태#

{
  "errors": [
    { "message": "Token not found", "extensions": { "code": "NotFound" } }
  ],
  "data": null
}

요청 제한#

GraphQL 작업은 API 토큰(jti)과 IP별로 단일 레이트 리밋 버킷을 공유합니다: 쿼리 600회/분, 뮤테이션 60회/분. 한도를 초과하면 errors[]에 extensions.code = RateLimited 오류 하나가 담긴 HTTP 200 응답이 반환됩니다. API는 429 상태나 Retry-After 헤더를 보내지 않으며, 재시도 타이밍 힌트는 오류의 extensions에 포함됩니다.

HTTP(GraphQL) 제한#

WebSocket 제한#

WebSocket 제한은 서버에서 구성 가능하므로 프로덕션에서는 이 기본값과 다를 수 있습니다. 제한은 IP가 아니라 연결 단위로 적용됩니다.

응답 헤더#

API는 레이트 리밋 헤더(X-RateLimit-*, Retry-After)를 보내지 않습니다. 상위 게이트웨이가 추가할 수 있으나 의존하지 마세요.

주의사항 및 멱등성#

인테그레이터가 가장 자주 틀리는 것들의 체크리스트.

금액과 크기#

• drops는 정수 — 처음부터 끝까지 BigInt. *UsdtDrops를 float로 파싱하지 마세요.
• 보내는 개설 금액(usdtDrops 또는 amountWei)은 수수료 차감 전 증거금이며 명목이 아닙니다.
• 명목 상한은 drops로 적용됩니다. 몇 drops 초과를 피하려면 증거금을 내림하세요 (「수수료 및 포지션 크기」 참조).
• 최대 레버리지는 모드별 고정 엔진 상한입니다(「토큰 속도 모드」 참조) — 직접 사용하세요.

토큰#

• 랜덤라이저는 무작위 rank(Competition | Private | Public)를 반환합니다. 토큰이 목록에 표시되거나 카피 트레이딩 가능해야 한다면 Public을 강제하세요.
• tokenCreate는 항상 잔액 기반 결제를 사용합니다 — 결제 유형은 재정의할 수 없습니다.
• tokens에는 서버 측 "활성" 플래그가 없습니다 — 클라이언트에서 endDate로 필터링하세요.

개설과 청산#

• tradeOpen은 usdtDrops(USDT 기준) 또는 amountWei(토큰 기준) 중 정확히 하나가 필요합니다 — 둘 다도, 둘 다 없음도 안 됩니다.
• tradeClose는 **USER_SELL**로 열린 포지션을 청산합니다.

테이크프로핏 / 스톱로스 (tradeLimit*)#

• tradeLimitCreate는 최소 하나의 트리거(SL 또는 TP)가 필요합니다.
• update 시 어떤 방향에 명시적 null을 주면 해제되고, 생략된 필드는 유지됩니다.
• tradeLimitUpdate는 모두 null인 입력을 거부합니다(Validation failed: input=MissingValue) — 해제하려면 tradeLimitDelete를 사용하세요.
• 방향별 삭제는 없습니다; tradeLimitDelete는 TP와 SL 둘 다 제거합니다.

구독 (WebSocket)#

• connection_init에서 payload: { Authorization: "Bearer <apiKey>" }로 인증하세요.
• positions 구독은 PublicPositionEvent 유니온을 스트리밍합니다 — PublicPositionOpenedEvent | PublicPositionClosedEvent | PublicPositionUpdatedEvent. 이벤트별 필드를 읽기 전에 type 필드로 구분하세요.
• PublicPositionClosedEvent는 positionId, tokenId, type, closeType, closedAt, closePriceUsdtDrops, receivedAmountUsdtDrops, pnlUsdtDrops를 가집니다. buyPriceUsdtDrops, collateralUsdtDrops, notionalUsdtDrops, leverageX10는 청산 이벤트가 아니라 PublicPositionOpenedEvent의 필드입니다.
• 청산 이벤트는 at-least-once이며 재전송되지 않습니다. 재연결 중 발행된 청산은 새 구독에서 누락됩니다 — 누락된 청산을 잡으려면 (재)구독 시 각 열린 포지션을 폴링하고 positionId로 중복 제거하세요.

WebSocket API#

실시간 데이터는 GraphQL over WebSocket 프로토콜(graphql-transport-ws)을 사용하는 WebSocket 연결로 전달됩니다. 실시간 가격 업데이트와 같은 subscription 작업에 사용하세요.

연결#

다음 주소로 WebSocket을 엽니다:

wss://public-api.catapult.trade/graphql

graphql-transport-ws 서브프로토콜을 협상합니다. 소켓이 열리면 connection_init 메시지를 보내고, 서버는 connection_ack로 응답합니다.

수명 주기#

1. 클라이언트가 graphql-transport-ws 서브프로토콜로 소켓을 엽니다.
2. 클라이언트 → {"type":"connection_init"}.
3. 서버 → {"type":"connection_ack"}.
4. 클라이언트 → 고유한 id와 GraphQL 문서를 포함한 subscribe.
5. 서버 → 하나 이상의 next 메시지, 그다음 complete.

구독#

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription($t: ID!) { priceTicks(tokenId: $t) { tokenId price } }",
    "variables": { "t": "<tokenId>" }
  }
}

데이터 메시지#

{
  "id": "1",
  "type": "next",
  "payload": { "data": { "priceTicks": { "tokenId": "tok_123", "price": "0.0123" } } }
}

구독 취소#

하나의 구독을 중지하려면 complete 메시지를 보내세요. 모두 중지하려면 소켓을 닫으세요.

{ "id": "1", "type": "complete" }

오류#

작업 수준 오류는 해당 id에 대한 error 메시지로 도착합니다:

{ "id": "1", "type": "error", "payload": [{ "message": "Token not found" }] }

10초 이내에 connection_init을 보내지 않은 연결은 코드 4408(연결 초기화 시간 초과)로 종료됩니다.