Tovanix
Tovanix

API 문서

Tovanix 오픈 API 연동 문서로, 서비스별로 나뉘어 있습니다: 멀티체인 결제, 에너지 임대, SMTP API, AI API, 가상 카드, 메일 발송, 오브젝트 스토리지, 신원 및 거래 위험 검증, MCP 연동. 실습 페이지: 컨트랙트 스튜디오, 결제 리플레이, AI 라우팅 실험실.

  • 멀티체인 결제
  • 에너지 임대
  • SMTP API
  • AI API
  • 가상 카드
  • 메일 발송
  • 오브젝트 스토리지
  • 신원 및 거래 위험 검증
  • MCP 연동

USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · HMAC-SHA256(결제) + RSA-2048(출금) 이중 서명 · 30초 정산 푸시

3단계 연동

  • 1 계정 등록 + 앱 생성 콘솔의 "내 앱"에서 app_id와 app_key를 받고 notify_url을 설정하세요 무료로 가입 →
  • 2 서명 헬퍼 구현 결제는 HMAC-SHA256(대칭), 출금은 RSA-2048(비대칭)을 사용합니다. 공식 SDK가 두 가지를 모두 감싸며 언어별 예제도 제공합니다
  • 3 모드를 고르고 첫 거래 실행 일대일(사용자에게 주소를 고정 연결, 지갑·계정 충전에 적합) · 순환(주문마다 주소를 생성, 이커머스 결제에 적합)

개요

Tovanix는 동시에 켤 수 있는 두 가지 결제 모드를 지원합니다:

일대일 모드

사용자가 고정 주소를 연결하고, 입금은 모두 능동적으로 푸시됩니다. 충전과 수금에 적합합니다.

  • 사용자가 고정 수신 주소를 연결
  • 입금 실시간 푸시 알림
  • 반복 결제 지원
  • 독립적인 서명 검증

순환 모드

주문을 만들 때 수신 주소를 동적으로 배정하고 시간이 지나면 회수합니다. 일회성 결제에 적합합니다.

  • 주소 동적 배정
  • 주문 만료 제어
  • 환율 자동 환산
  • 결제 페이지

서명 알고리즘

일대일 모드의 푸시 알림은 app_key가 아니라 webhook_secret으로 서명합니다.

1. HMAC-SHA256을 사용하고 secret은 HMAC 키 파라미터로 넘깁니다(문자열 뒤에 붙이지 않습니다)

2. 서명 결과는 소문자 64자 16진수 문자열이며 비교는 대소문자를 구분합니다

3. 주문을 만들 때 amount는 소수점 두 자리로 맞춰야 하고(예: 100.00), timeout은 정수 문자열이어야 합니다. timeout을 넘기지 않아도 서명에는 timeout=0으로 포함해야 합니다(서버는 언제나 timeout을 서명 문자열에 넣습니다)

4. 값이 빈 필드는 서명 계산에서 제외합니다

리플레이 방지

가로챈 요청이 재전송되는 것을 막기 위해 서명 요청에 타임스탬프와 nonce를 넣을 수 있으며, 둘 다 서명 대상에 포함됩니다. 주문 종료, 주소 바인딩, 주소 바인딩 해제 세 엔드포인트에서는 필수이며 없으면 400이 반환됩니다. 다른 엔드포인트에서는 선택입니다.

/api/v1/pay/close: timestamp와 nonce가 필수입니다. /api/v1/pay/bind-address, /api/v1/pay/unbind-address: sign_ts와 nonce가 필수입니다(타임스탬프 필드 이름으로 timestamp도 받습니다). /api/v1/pay/get-address도 sign_ts를 사용하지만 선택입니다. 주문 생성, 주문 조회, 앱 설정은 timestamp를 사용하며 선택입니다. 타임스탬프와 nonce가 모두 있으면 서버가 시간 창과 nonce를 검사하고, 하나만 있거나 둘 다 없으면 서명만 검증합니다.

timestamp는 서버 시각과 300초 넘게 차이 나면 안 되므로 NTP로 서버 시각을 맞춰 두세요. nonce는 5분 안에 재사용할 수 없습니다. 타임스탬프가 범위를 벗어나거나 nonce가 중복되면 요청이 거부됩니다. 주문 생성과 주문 조회는 HTTP 400을, 다른 엔드포인트는 401을 반환하며 이유는 응답의 message 필드에서 확인할 수 있습니다.

주소 연결

POST /api/v1/pay/bind-address

사용자에게 고정 결제 주소를 배정합니다. 이미 연결되어 있으면 기존 주소를 반환합니다.

연결 조회

POST /api/v1/pay/get-address

사용자에게 연결된 결제 주소를 조회합니다.

주소 연결 해제

POST /api/v1/pay/unbind-address

사용자의 결제 주소 연결을 해제합니다.

주문 생성

POST /api/v1/pay/create

결제 주문을 만들면 시스템이 수신 주소를 자동으로 배정합니다.

응답 필드

amount는 숫자와 문자열을 모두 받습니다: 100 또는 "100". 다만 서명할 때는 언제나 "100.00"처럼 소수점 두 자리로 맞추세요.

주문 조회

GET /api/v1/pay/query

가맹점 주문번호로 주문 상태를 조회합니다. 파라미터는 URL Query로 전달합니다.

주문 종료

POST /api/v1/pay/close

결제되지 않은 주문을 수동으로 종료하면 주소가 회수됩니다. 대기 중(status=0)인 주문만 종료할 수 있습니다.

앱 설정 조회

GET /api/v1/pay/app-config

앱 모드 설정, 활성화된 토큰, 푸시 설정 등을 조회합니다. 민감한 정보는 노출되지 않습니다.

일대일 푸시 알림

연결된 주소로 입금이 들어오면 시스템이 설정된 notify_url로 POST 요청을 보냅니다.

푸시 알림은 webhook_secret으로 서명하며, 앱 상세 페이지에서 확인하거나 다시 발급할 수 있습니다.

푸시 필드

수신하면 HTTP 200 또는 {"code": 0}을 반환하세요. 그렇지 않으면 시스템이 자동으로 재시도합니다(최대 10회, 지수 백오프).

주문 콜백 알림

순환 모드 주문이 결제되면 시스템이 notify_url로 콜백을 보냅니다.

콜백 알림은 webhook_secret으로 서명하며, 앱 상세 페이지에서 확인하거나 재설정할 수 있습니다.

콜백 필드

2xx 상태 코드를 반환하면 전달 완료로 보며 응답 본문은 확인하지 않습니다({"code": 0}를 반환해도 상태 코드가 2xx가 아니면 실패입니다). 2xx가 아닌 응답, 10초 안에 응답 없음, 연결 실패, 리디렉션은 모두 실패로 보고 30초·1분·2분·5분 뒤 각각 재시도한 다음 10분마다 최대 10회 재시도합니다. 재시도할 때 notify_id는 그대로이고 sign_ts, nonce, 서명은 새로 바뀝니다. notify_id로 중복을 제거하세요.

환율 조회

GET /api/v1/rate

두 통화 사이의 실시간 환율을 가져옵니다

금액 환산

POST /api/v1/convert

실시간 환율로 금액을 환산합니다

환율 일괄 조회

GET /api/v1/rates

여러 통화의 환율을 조회합니다(통화 코드를 쉼표로 구분)

전체 환율

GET /api/v1/rates/all

지원하는 모든 통화의 환율 목록을 가져옵니다

법정화폐 환율

GET /api/v1/rates/fiat

지정한 법정화폐를 기준으로 모든 법정화폐 환율을 가져옵니다(30종 이상, 지역별로 묶임)

주문 상태

주문은 다음 상태를 거칩니다:

오류 코드

결제 API(/api/v1/pay/*)의 공통 오류 코드입니다. 출금 API의 오류 코드는 참고 자료 섹션에 있습니다.

출금 개요 / 사전 조건

출금 API는 멀티체인 결제 상품의 자금 지급 쪽입니다. 중앙 지갑으로 모인 자산을 프로그램으로 외부 주소에 보냅니다. RSA-2048 상호 서명 + IP 허용 목록 + 지연 브로드캐스트 + 다채널 알림 차단 + 온체인 확인 콜백을 제공합니다.

출금 API는 시스템 수탁 모드에서 중앙 지갑으로 모인 자산만 사용합니다. 결제 앱이 자체 수탁 모드라면 자금이 사용자 소유 주소로 바로 들어가고 플랫폼이 모으지 않으므로, "모여서 출금 대기 중"인 잔액이 생기지 않아 이 API로는 출금할 수 없습니다.

4단계로 활성화

  • 콘솔의 "멀티체인 결제 → API 출금" 설정 페이지로 이동합니다
  • 사용자 쪽에서 RSA-2048 키 페어를 로컬로 생성하고 공개 키를 업로드합니다
  • IP 허용 목록을 하나 이상 설정합니다(필수). 필요하면 주소 허용 목록 / 건당 한도 / 출금 지연도 설정합니다
  • 마스터 스위치를 켜면 시스템이 계정용 플랫폼 키 페어를 자동 생성합니다. 콜백 검증을 위해 플랫폼 공개 키를 복사해 두세요

서명 · RSA-2048 (출금)

모든 /api/v1/withdraw* 엔드포인트는 다음 요청 헤더를 담아야 합니다. 결제 API의 대칭 HMAC과 달리 출금은 비대칭 RSA를 사용하며, 플랫폼은 사용자 공개 키만 보관하므로 위험은 개인 키가 유출되는 경우뿐입니다.

  • X-API-Key — 플랫폼 API 키의 API Key(콘솔의 「도구와 설정 → API 관리」에서 발급). 이 키에는 withdraw 권한이 있어야 합니다
  • X-Timestamp — 현재 unix 밀리초. 서버와의 시각 차이는 60초 이하여야 합니다
  • X-Nonce — 일회용 nonce(uuid). 5분 안에는 재사용할 수 없습니다
  • X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64

서명 문자열 연결 규칙

여기서 BODY는 원본 HTTP 본문입니다(JSON 문자열 그대로이며 다시 직렬화하지 마세요). GET 요청에서는 BODY가 빈 문자열입니다.

위의 계정 단위 RSA 서명과 계정 IP 허용 목록 외에도, 사용하는 API 키에 withdraw 권한이 있어야 하며 그 키 자체의 출발지 IP 화이트리스트도 적용됩니다. 권한이 없으면 403 / 4032가, 출발지 IP가 키의 화이트리스트에 없으면 403 / 4033이 반환됩니다. 이 두 검사는 /api/v1/withdraw, /api/v1/balance/withdrawable, /api/v1/fee/quote에 적용됩니다. 이번 변경 전부터 있던 키에는 withdraw 권한이 자동으로 부여되어 영향이 없으며, 새로 만드는 키는 「도구와 설정 → API 관리」에서 선택하세요. 이 키에 부여된 권한은 GET /api/v1/whoami(X-API-Key + X-Secret-Key 또는 HMAC 서명으로 호출)로 확인할 수 있습니다.

출금 결과 콜백

주문을 넣을 때 본문에 callback_url을 넘길 수 있고, 출금이 완료 / 실패 / 취소되면 플랫폼이 그 URL로 결과를 POST 합니다.

  • 콜백 본문은 플랫폼 개인 키로 서명되어 X-Platform-Signature 헤더에 담깁니다
  • 사용자 쪽에서는 플랫폼 공개 키(설정 페이지에서 복사 가능)로 서명을 검증해야 하며, 검증 알고리즘은 요청 방향과 같습니다
  • 실패하면 1분 / 5분 / 30분 / 2시간 / 6시간 / 24시간 간격으로 총 6회 재시도한 뒤 포기하고 수동 처리로 넘깁니다
  • 사용자 쪽에서는 HTTP 2xx를 반환해야 하며, 2xx가 아니면 실패로 처리됩니다

요청 헤더

  • X-Timestamp — 현재 unix 밀리초 타임스탬프
  • X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(플랫폼 개인 키, 서명 문자열))

서명 문자열 연결 규칙

PATH는 callback_url의 경로 부분(호스트와 쿼리 문자열 제외), BODY는 받은 요청 본문 원문이며 다시 직렬화하지 마세요. 설정 페이지의 플랫폼 공개 키로 검증합니다.

status 값은 completed / failed / failed_onchain / cancelled 중 하나입니다. 금액과 수수료는 문자열입니다. created_at, completed_at은 unix 초이며 완료 시각이 없으면 0입니다. 같은 주문을 재시도해도 body는 같으므로 order_id로 중복을 제거하세요.

출금 요청

POST /api/v1/withdraw

주문을 넣으면 상태가 pending이 되고, 지연 시간이 지나면 워커가 자동으로 브로드캐스트합니다. 그 사이에는 콘솔에서 일시 정지 / 즉시 처리 / 취소할 수 있습니다.

필드 설명

  • chain — string — 예 — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
  • symbol — string — 예 — USDT / TRX / ETH 등
  • amount — string — 예 — 소수점 18자리까지. 부동소수점 오차를 피하려면 문자열을 쓰세요
  • to_address — string — 예 — 대상 주소(주소 허용 목록을 켰다면 먼저 콘솔에 등록해야 합니다)
  • memo — string — 아니요 — 설명 문구(500자 이하). 알림과 함께 계정 사용자에게 전달됩니다
  • callback_url — string — 아니요 — 결과 콜백 URL. 비우면 콜백을 보내지 않습니다
  • request_id — string — 강력 권장 — 멱등 키. 같은 계정에서 같은 값을 다시 보내면 원래 주문을 반환합니다. 체인·심볼·주소·금액이 다르면 409를 반환하고 주문을 만들지 않습니다 전달하지 않으면 멱등성 보호가 없습니다. 시간 초과나 5xx 이후 재시도하면 실제 출금이 한 번 더 생성됩니다.

응답 필드

  • order_id — string — 출금 주문 ID. "단건 출금 조회" 엔드포인트에서 사용합니다
  • status — string — 주문의 현재 상태로, 조회 API의 status_label과 같은 값입니다. 새 주문은 pending(잔액 차감 완료, 리스크 지연과 브로드캐스트 대기)이며, 같은 request_id로 다시 제출하면 그 주문의 실제 상태가 반환되어 이미 completed, failed 등일 수 있습니다
  • amount — string — 출금 금액(문자열)
  • fee — string — 예상 수수료(주문 시점 기록)
  • fee_mode — string — in_amount = 금액에서 차감(수령액 = 금액 − 수수료, 잔액에서 금액만큼 차감), out_amount = 별도 청구(수령액 = 금액, 잔액에서 금액 + 수수료 차감)
  • delayed_until — string | null — 예정된 브로드캐스트 시각(리스크 지연). null이면 지연 없음

단건 출금 상태 조회

GET /api/v1/withdraw/:id

주문 상세를 반환하며 상태 폴링에 쓸 수 있습니다(그래도 콜백 사용을 권장합니다).

응답 필드

  • id — string — 출금 주문 ID
  • request_id — string — 넘긴 멱등 키
  • chain / symbol — string — 체인 / 토큰 심볼
  • amount / expected_fee / fee_mode — string — 출금 금액 / 주문 시점에 기록된 예상 수수료 / 수수료 방식(in_amount, out_amount)
  • to_address — string — 대상 주소
  • memo — string — 메모(TAG/Memo)
  • status / status_label — int / string — 상태 코드와 표시 문구. 아래 "주문 상태"를 참고하세요
  • tx_hash — string — 온체인 트랜잭션 해시(브로드캐스트 후 채워집니다)
  • fail_reason — string — 실패 사유(실패한 경우 채워집니다)
  • delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — 단계별 시각: 예정 브로드캐스트 / 브로드캐스트 / 온체인 확인 / 일시 정지 / 취소. 도달하지 않은 단계는 null입니다
  • callback_url / callback_retry — string / int — 결과 콜백 URL / 지금까지의 재시도 횟수
  • callback_state — string — 콜백 상태: pending = 아직 호출하지 않았거나 재시도 중, success = 2xx 수신, giveup = 재시도 소진, no_url = 콜백 미설정
  • created_at — string — 생성 시각

사용 가능 잔액 조회

GET /api/v1/balance/withdrawable

이 계정의 체인별 × 자산별 "모여서 출금 대기 중" 잔액을 반환합니다. API 출금에는 이 부분만 사용할 수 있습니다.

2단 구조입니다: 체인 → 토큰 심볼 → 출금 가능 잔액(문자열). 잔액이 0보다 큰 항목만 반환합니다.

수수료 예상

관리자가 해당 체인 × 심볼에 설정해 둔 선차감 수수료를 반환합니다(OKX 방식의 고정 값).

응답 필드

  • chain / symbol / amount — string — 요청 파라미터 그대로 반환: chain / symbol / amount
  • fee_amount — string — 수수료 금액
  • fee_asset — string — 수수료 정산 자산

전체 cURL 예제

서명과 요청까지 전체 흐름입니다. 터미널에 그대로 붙여 넣어 테스트할 수 있습니다.

주문 상태 · 출금

상태 기계: pending → broadcasted → completed / failed_onchain. 그 사이에 paused / cancelled / failed가 될 수 있습니다.

  • 0 — pending — 잔액이 차감되었고 지연 만료 / 브로드캐스트를 기다립니다
  • 1 — completed — 온체인 트랜잭션이 성공적으로 확인되었습니다(콜백 대상)
  • 2 — failed — 브로드캐스트 전에 실패했습니다(잔액 환불됨)
  • 3 — broadcasted — 브로드캐스트했고 온체인 확인을 기다립니다
  • 4 — failed_onchain — 온체인에서 실패했습니다(revert 또는 오래도록 채굴되지 않음. 잔액 환불됨)
  • 5 — paused — 사용자가 수동으로 일시 정지했습니다. 재개하거나 취소할 수 있습니다
  • 6 — cancelled — 사용자가 수동으로 취소했습니다. 잔액이 환불되었습니다
  • 7 — broadcasting — 브로드캐스트 중(이중 브로드캐스트를 막는 짧은 과도 상태)

오류 코드 · 출금 API

  • 400 — 파라미터 오류 / 잔액 부족 / 금액이 체인 × 심볼 한도를 벗어남 / 주소 검증 실패
  • 401 — API Key 오류 / timestamp 편차 과다 / nonce 재사용 / 서명 검증 실패
  • 403 — 계정에 API 출금이 켜져 있지 않음 / IP가 계정 허용 목록에 없음. 또는 사용한 API 키에 withdraw 권한이 없음(code 4032), 출발지 IP가 그 키의 화이트리스트에 없음(code 4033)
  • 404 — 주문을 찾을 수 없음
  • 429 — 요청이 너무 많습니다(계정당 초당 최대 10회). 응답 헤더에 Retry-After: 1이 있으므로 1초 기다린 뒤 같은 request_id로 다시 시도하세요
  • 5xx — 플랫폼 오류이며 재시도할 수 있습니다(같은 request_id를 쓰면 멱등성이 보장됩니다)

출금 보안 안내

  • 개인 키를 로컬에서 안전하게 보관하세요. 유출되면 다른 사람이 대신 출금할 수 있습니다
  • API 출금을 켜기 전에 IP 허용 목록을 반드시 설정해야 합니다. 허용되지 않은 IP는 서명이 유효해도 거부됩니다
  • "출금 주소 허용 목록"도 함께 켜고 알려진 대상 주소를 미리 등록하시길 권장합니다
  • 계정 사용자가 2FA를 켜면, 지연 시간 안에 콘솔에서 2FA로 주문을 즉시 처리하거나 취소할 수 있습니다
  • 큰 금액의 주문은 지연을 길게(몇 시간) 두어 알림을 보고 수동으로 차단할 시간을 확보하는 것을 고려하세요

관련 페이지: 멀티체인 암호화폐 결제 · SMTP 통합 API · AI 서비스

불러오는 중…