Ownbit 멀티시그 API v1 (1단계)
자체 시스템에서 Ownbit 멀티시그로 지급 목록을 넘길 수 있습니다. 웹 콘솔에서 만든 API 키로 초안을 제출하면, 서명자가 모든 줄을 검토한 뒤 휴대폰에서 시작합니다. API는 자금을 옮기지 않습니다.
2026-11-18 버전(초안은 lineId 단위로 변경, 초안 상태는 다섯 가지). 이 문서는 API의 1단계를 설명합니다. 문서에 나오는 모든 키, 해시, 주소, IP 주소는 꾸며낸 예시입니다(IP 주소는 문서용으로 예약된 범위에서 가져왔습니다). USDT-TRC20 컨트랙트 주소만 실제 공개 주소입니다.
1. API가 하는 일
여러분의 시스템(아래에서 "봇")은 Ownbit 멀티시그 하나에 대한 지급 목록, 즉 초안을 Ownbit에 넘기고, 나중에 그 초안이 어떻게 되었는지 조회합니다. 서명자가 시작했는지, 거절되었는지, 철회되었는지, 만료되었는지입니다.
API는 자금을 절대 옮기지 않습니다. 초안은 멀티시그의 서명자가 Ownbit 웹 콘솔에서 초안을 열고, 자신의 휴대폰에서 시작하고, 멀티시그의 충분한 멤버가 각 거래에 서명해야(m of n) 비로소 지급이 됩니다. 서명자는 시작하기 전에 모든 줄을 보고, Ownbit가 지급에 대해 수행하는 모든 검사는 그대로 실행되며, 서명자는 초안을 거절할 수 있습니다. 키로는 서명, 지급 시작, 승인, 거절을 할 수 없고 멀티시그의 정책, 화이트리스트, 멤버도 바꿀 수 없습니다.
키로 할 수 있는 일:
| 호출 | 권한 | 하는 일 |
|---|---|---|
GET /whoami | drafts:read | 키와 그 멀티시그 정보, 오늘의 호출 수를 알려 줍니다 |
POST /drafts | drafts:submit | 초안을 제출하거나(1~500줄), 아무도 시작하지 않은 초안을 변경합니다. 여러분의 lineId로 줄을 추가, 교체, 삭제합니다 |
GET /drafts | drafts:read | 이 키의 초안을 변경이 오래된 것부터 커서와 함께 나열합니다 |
GET /drafts/{draftId} | drafts:read | 초안 하나를 줄과 함께 조회합니다 |
DELETE /drafts/{draftId} | drafts:submit | 아무도 시작하지 않은 초안을 철회합니다 |
2. 1단계 범위
- TRON 멀티시그만 지원합니다. 줄은
TRX또는USDT(USDT-TRC20, 컨트랙트TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t)로 지급하며, 둘 다 소수점 6자리입니다. - IPv4만 지원합니다. API는 IPv4로만 접속할 수 있고(1단계에서
api.bittool.com에는 IPv6 주소가 없습니다), 키의 허용 목록에는 IPv4 범위만 들어갑니다. - 웹훅은 없습니다. 봇이 폴링합니다(빈도는 10절 참고).
- 초안 하나에 최대 500줄입니다. 서명자는 큰 초안을 휴대폰에서 두 개의 요청으로 나눠 시작할 수 있지만, 여러분 쪽에서 달라지는 것은 없습니다.
3. 기본 URL과 전송
https://api.bittool.com/ownbit/api/v1- 1단계에서는 IPv4만 지원합니다. 이 호스트 이름에는 IPv6 주소가 없으므로 IPv4와 IPv6를 모두 가진 서버도 IPv4로 호출하게 되고, IPv4 허용 목록과 대조됩니다.
- HTTPS만 허용합니다. HTTPS로 도착하지 않은 요청은
403 https_required로 거부되며 리디렉션되지 않습니다. 평문 HTTP로 보낸 적이 있는 키는 유출된 것으로 간주해야 합니다. 취소하고 새로 만드세요. HTTPS 응답에는Strict-Transport-Security: max-age=31536000이 붙습니다. - UTF-8 JSON.
POST요청은Content-Type: application/json을 보냅니다(; charset=utf-8접미사는 괜찮습니다). 요청 본문은 최대 256 KiB입니다. - 시각은 밀리초가 포함된 UTC 기준 ISO 8601 문자열입니다. 예:
2026-11-17T06:00:00.000Z. - 모든 응답에는
Cache-Control: no-store,Pragma: no-cache,X-Request-Id(req_뒤에[0-9a-z]16자)가 붙습니다. 오류 본문은 이 값을requestId로 다시 담습니다. 지원팀에 문의할 때 이 값을 알려 주세요. - CORS는 없습니다. 브라우저 페이지에서는 API를 호출할 수 없습니다. 서버에서 호출하세요.
- 요청은 엄격하게, 응답은 유연하게. API가 모르는 필드가 있는 요청은 거부됩니다(
400 invalid_request). 응답에는 시간이 지나면서 새 필드가 추가될 수 있으니, 모르는 필드는 무시하세요.
4. 키
- 발급 방법. 멀티시그의 멤버가 Ownbit 웹 콘솔의 멀티시그 API 탭에서 키를 만들고(서명자 역할의 멤버라면 누구나 가능), Ownbit 앱으로 자신의 휴대폰에서 승인합니다. 키는 휴대폰이 승인한 직후 그 브라우저 탭에 단 한 번 표시됩니다. Ownbit는 키의 해시만 보관하므로 다시 보여 줄 수 없습니다. 잃어버렸다면 취소하고 새로 만드세요.
- 형식.
obk_뒤에[0-9A-Za-z]43자(총 47자, 약 256비트의 무작위성). Ownbit는 키를 표시하는 모든 곳에서 마지막 4자만obk_…defg형태로 보여 줍니다. - 생성 시 정하는 옵션. 이름(최대 30자, 멀티시그의 키 사이에서 고유), 휴대폰 승인 시점부터 계산하는 유효 기간 30일, 90일(기본값), 180일, 365일, 2년 또는 5년, 각각
/8~/32인 최대 20개 범위의 IPv4 허용 목록(빈 목록은 모든 주소를 뜻함), 그리고 키가 임의의 24시간 동안 제출할 수 있는 최대 지급 줄 수(1~10,000, 기본값 1,000). - 권한. 1단계의 모든 키는
drafts:submit과drafts:read를 가집니다. - 멀티시그 하나. 키 하나는 멀티시그 주소 하나를 대상으로 합니다. 그 주소의 TRX와, 있다면 같은 주소의 USDT입니다. Ownbit는 한 주소를 토큰마다 하나씩 여러 멀티시그로 나열할 수 있는데, 이들은 같은 키를 공유합니다. 키는 다른 멀티시그의 데이터를 절대 볼 수 없습니다.
- 멀티시그당 최대 5개 키(승인 대기 중인 키 포함).
- 취소. 어느 멤버든 웹 콘솔이나 Ownbit 앱에서 언제든지 키를 취소할 수 있습니다. 취소되었거나 만료된 키는 즉시 실패합니다. 키를 취소하면 그 키의 초안 중 아무도 시작하지 않은 것도 거절됩니다(사유
key_revoked). 이미 시작된 초안은 계속 진행됩니다. - 알림. 키가 승인되거나 취소되면 모든 멤버의 휴대폰에 알림이 갑니다. 예상하지 못한 알림을 팀이 받았다면 그 키를 취소하세요.
5. 인증
모든 호출에서 키를 보내되, 반드시 다음 헤더에만 넣으세요.
Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg키를 URL, 쿼리 문자열, 본문에 절대 넣지 마세요.
curl -sS https://api.bittool.com/ownbit/api/v1/whoami \
-H "Authorization: Bearer $OWNBIT_API_KEY"- 키와 관련된 모든 문제는 같은 응답을 받습니다:
401 {"error":{"code":"unauthorized","message":"Invalid or unusable API key"},"requestId":"req_…"}. 헤더가 없거나 형식이 잘못된 경우, 알 수 없는 키, 아직 승인되지 않은 키, 취소되었거나 만료된 키, 호출 주소가 키의 허용 목록 밖인 경우, 생성자가 더 이상 멤버가 아니거나 서명자 역할이 없는 경우, 멀티시그가 더 이상 활성 상태가 아닌 경우가 모두 여기에 해당합니다. 멀티시그의 멤버는 웹 콘솔에서 각 키의 마지막 거부와 그 사유를 볼 수 있으니, 원인을 알 수 없으면 멤버에게 물어보세요. - 호출에 필요한 권한이 없는 유효한 키는
403 forbidden을 받습니다. 401은 재시도해도 사라지지 않습니다. 중단하고 사람이 확인하게 하세요(10.4절: 반복된 실패는 여러분의 주소를 차단합니다).
6. 호출
6.1 GET /whoami
{"keyId":"kid_0123456789abcdef","name":"Payout bot","hint":"defg","perms":["drafts:submit","drafts:read"],
"createdAt":"2026-11-17T06:00:00.000Z","expiresAt":"2027-02-15T06:05:00.000Z","ipAllow":["203.0.113.0/24"],
"dailyLines":1000,"linesUsed24h":200,
"callsToday":2880,"dailyCalls":10000,"multisigCallsToday":3105,"multisigDailyCalls":20000,
"callsResetAt":"2026-11-18T00:00:00.000Z",
"multisig":{"msId":4001,"chain":"TRX","address":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","name":"Payroll",
"isEnterprise":true,"requiredNum":2,"ownerNum":4,"symbols":["TRX","USDT"],"defaultSymbol":"TRX"}}dailyLines,linesUsed24h: 키의 줄 수 한도와 지난 24시간 동안 제출한 줄 수.callsToday,dailyCalls: 00:00 UTC 이후 이 키의 호출 수(이번 호출 포함)와 일일 호출 한도.multisigCallsToday,multisigDailyCalls: 멀티시그의 모든 키를 합친 같은 값.callsResetAt: 일일 카운트가 다시 시작되는 시각(10절).multisig.symbols: 지급에 쓸 수 있는 심볼.multisig.defaultSymbol:symbol이 없는 줄이 지급되는 심볼. TRON 멀티시그에서는 이 값이TRX이며,USDT가 아닙니다: 모든 줄에symbol을 보내세요(6.2절).requiredNum/ownerNum: 각 지급에 필요한 서명 수 / 전체 멤버 수.
6.2 POST /drafts
한 번의 호출로 초안을 만들고, 이후 같은 clientRequestId로 호출하면 그 초안을 변경합니다. 줄을 추가하고, 교체하고, 삭제하며, 각 줄은 여러분이 정한 lineId로 지정합니다. 초안은 아무도 시작하지 않은 동안(상태 submitted)에만 변경할 수 있습니다.
요청(정확히 다음 키만 허용하며, 그 밖의 키는 400 invalid_request):
{"clientRequestId":"payout-2026-11-17-001",
"lines":[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},
{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT"}]}줄 하나를 추가하고, po-1을 변경하고, po-2를 삭제하는 이후 호출:
{"clientRequestId":"payout-2026-11-17-001",
"lines":[{"lineId":"po-3","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"0.03","symbol":"USDT"},
{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"130","symbol":"USDT","memo":"INV-1001"}],
"remove":["po-2"]}| 필드 | 규칙 |
|---|---|
clientRequestId | [A-Za-z0-9._:-] 1~64자. 이 지급 목록에 대한 여러분 자신의 ID입니다. 멀티시그의 초안 하나를 영구히 가리킵니다(6.2.2절) |
lines | 0~500개의 객체. 각 객체에는 아래 키만 들어갑니다. 첫 호출에는 최소 하나를 보내야 합니다 |
remove | 선택. 초안에서 뺄 줄의 lineId 목록. 초안에 없는 lineId는 무시되므로 재시도해도 안전합니다. 같은 lineId가 lines와 remove에 동시에 있을 수는 없습니다 |
lineId | 필수. [A-Za-z0-9._:/-] 1~64자. 줄에 대한 여러분 자신의 ID로, 초안 안에서 고유해야 합니다(다른 clientRequestId에서는 새로 시작합니다). 초안에 이미 있는 lineId는 그 줄을 제자리에서 교체하고, 새 ID는 끝에 추가됩니다. 여러분에게 그대로 돌려주며, 체인에 기록되지 않고 서명자에게도 보이지 않습니다 |
to | TRON 주소(34자, base58check). 멀티시그 자신의 주소, TRON 제로 주소 T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb, USDT 컨트랙트(그곳으로 보낸 토큰은 사라집니다)는 안 됩니다 |
amount | ^(0|[1-9][0-9]*)(\.[0-9]+)?$에 맞는 문자열. 0보다 크고, 보낸 그대로 셌을 때 소수점 이하 최대 6자리("1.0000000"은 amount_decimals로 거부되고, "80.500000"은 허용되어 "80.5"로 저장됩니다), 최소 단위로 최대 9223372036854775807. JSON 숫자가 아니라 반드시 문자열로 보내세요. Ownbit는 정규형으로 저장합니다. 소수부 끝의 0을 지우고, 그다음 남은 소수점만 있으면 지웁니다("80.50"은 "80.5"가, "2.0"은 "2"가 됩니다) |
symbol | TRX 또는 USDT. 모든 줄에 보내세요. 생략하면 그 줄은 멀티시그의 defaultSymbol로 지급되며, TRON 멀티시그에서는 이 값이 TRX입니다. 즉 symbol 없는 USDT 지급은 같은 숫자의 TRX 지급이 됩니다. 멀티시그가 그 심볼을 보유하고 있어야 합니다(whoami의 symbols) |
memo | 선택. 최대 80자. , ' " \ 사용 불가. 제어 문자, 줄바꿈 문자, 보이지 않는 문자 사용 불가. 앞뒤 공백 불가. 예약된 메모(대소문자 구분 없이 admin:으로 시작하거나, -no-broadcast를 포함하거나, ***br***로 끝나는 것) 불가. 생략과 ""는 같습니다 |
Ownbit는 먼저 remove의 줄을 삭제하고, 그다음 lines의 각 줄을 교체하거나 추가한 뒤, 초안 전체를 검사합니다. 최대 500줄, 최소 1줄이어야 하고, to, 정규형 amount, symbol이 모두 같은 줄이 둘 이상 있으면 안 됩니다(첫 번째 줄이 서명을 기다리는 동안 체인이 두 번째 줄을 중복으로 거부합니다). 보내는 모든 줄은 첫 호출 때와 똑같이 검사되며, 하나라도 거부되면 아무것도 바뀌지 않습니다.
응답:
| 상태 | 본문 | 경우 |
|---|---|---|
201 | {"draft":<draft>} | 새 초안. 상태는 submitted, 리비전 1, 모든 줄은 pending |
200 | {"draft":<draft>} | 초안이 변경되었거나(revision이 1 증가), 호출이 아무것도 바꾸지 않은 경우(재시도): 현재 상태의 초안 |
409 not_editable | details.draftId, details.status | 초안이 더 이상 submitted가 아닌 경우(서명자가 시작했거나, 철회·거절·만료됨): 아무것도 바뀌지 않았습니다 |
409 idempotency_conflict | 같은 멀티시그의 다른 키가 이미 그 clientRequestId를 사용한 경우 | |
410 gone | 이 clientRequestId의 초안이 삭제된 경우(보관 기간, 7.3절) | |
422 invalid_lines | details.errors | 하나 이상의 줄이 유효하지 않거나 초안이 비게 되는 경우. 아무것도 바뀌지 않았습니다 |
429 daily_limit | details.scope | 키 또는 멀티시그의 24시간 줄 수 한도를 넘게 되는 경우(10절). details.neverFits: true이고 Retry-After가 없으면 이 호출 하나만으로 한도보다 줄이 많은 것이므로 기다려도 소용없습니다. 호출당 줄 수를 줄여 보내세요 |
details.errors는 처음 50개의 문제를 {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"} 형태로 나열합니다. 사유: line_id_invalid, line_id_duplicate, address_invalid, address_self, address_zero, address_contract, amount_invalid, amount_zero, amount_decimals, amount_too_large, symbol_unknown, symbol_unavailable, memo_invalid, memo_reserved, duplicate_line, draft_empty(line과 lineId는 null: 삭제하면 줄이 하나도 남지 않습니다. 대신 초안을 철회하세요, 6.5절).
6.2.1 초안
전체 형태(목록에서의 형태에는 lines가 없습니다):
{"draftId":"drf_0123456789abcdefghijklmn","clientRequestId":"payout-2026-11-17-001","status":"started","revision":1,
"createdAt":"2026-11-17T06:10:00.000Z","updatedAt":"2026-11-17T06:31:12.000Z","startedAt":"2026-11-17T06:31:12.000Z","lineCount":2,
"contentHash":"cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4",
"totals":[{"symbol":"USDT","amount":"205.5"}],"counts":{"started":2},"rejection":null,
"lines":[{"index":0,"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001",
"repeated":false,"state":"started"},
{"index":1,"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":"",
"repeated":false,"state":"started"}]}draftId:drf_뒤에[0-9a-z]24자.revision: 새 초안은 1이며, 초안을 변경한 호출이 있을 때마다 1씩 늘어납니다.startedAt: 서명자가 자신의 휴대폰에서 초안을 처음 시작한 시각, 그 밖에는null. 서명자가 다시 시작해도 바뀌지 않습니다.lines[].lineId: 여러분이 정한 줄의 ID.lines[].index: 0부터 시작하는 현재 위치(앞의 줄이 삭제되면 바뀌므로 줄은lineId로 대조하세요).memo는 값이 없으면""입니다.lines[].state: 항상 초안의 상태를 따릅니다(7.2절). 1단계에서는 줄에 거래 ID, 해시, 서명 수, 오류가 담기지 않습니다. 지급은 8절에 따라 확인하세요.totals: 심볼별 합계.counts: 상태별 줄 수(줄이 있는 상태만).repeated: 이 멀티시그의 최근 7일 이내 다른 초안에 주소, 금액, 심볼이 같은 줄이 있으면true. 서명자는 이 표시를 보고, 초안을 시작하기 전에 확인해야 합니다. 이 표시를 보면 여러분의 시스템도 점검하세요.rejection: 초안이 거절되었으면{"reason","note","at"}, 그 밖에는null. 사유:whitelist,address,amount,duplicate,other(웹 콘솔에서 서명자가 고르며 한 줄짜리note를 덧붙일 수 있음),phone(서명자가 휴대폰에서 거절함,note없음), 그리고key_revoked. API는 어느 멤버가 거절했는지 절대 알려 주지 않습니다.
6.2.2 재시도와 변경
clientRequestId는 멀티시그의 초안 하나를 영구히 가리킵니다. 초안이 보관되는 동안, 그리고 초안이 삭제된 뒤 365일 동안 사용된 상태로 남습니다(410). 초안을 만든 키만 그 초안을 변경할 수 있으며, 같은 멀티시그의 다른 키는409 idempotency_conflict를 받습니다(키를 교체한 뒤에는 새 ID를 쓰세요). 예를 들어 날짜와 일련번호를 조합해 ID가 영원히 고유하도록 만드세요.- 모든 호출은 안전하게 재시도할 수 있습니다. 타임아웃이나 네트워크 오류가 나면 같은 요청을 다시 보내세요. 보낸 줄은 같은 내용으로 자기 자신을 교체하고 삭제한 줄은 이미 없으므로, 응답은 현재 상태의 초안이며 초안이 두 개 생기거나 줄이 중복되는 일은 없습니다.
- 변경은 초안이
submitted인 동안에만 가능합니다. 서명자가 시작하면 호출은409 not_editable로 응답합니다. 지급하면 안 되는 줄은 서명자에게 거절해 달라고 요청하고, 새 줄은 새clientRequestId로 보내세요. - 서명자는 초안을 연 시점의 모습으로 봅니다. 서명자가 열어 둔 동안 초안이 바뀌면 콘솔이 시작을 거부하고 다시 열도록 안내합니다.
- 같은 ID로 동시에 두 번 호출하면 하나씩 차례로 적용됩니다.
6.2.3 콘텐츠 해시
contentHash는 초안의 줄을 현재 순서대로 담은 압축 JSON 배열의 UTF-8 바이트에 대한 소문자 16진수 SHA-256입니다. 각 줄은 {"lineId","to","amount","symbol","memo"}를 이 순서로 쓰고, 금액은 정규형으로, 심볼은 항상 명시하며, 값이 없으면 ""로 씁니다(memo가 없을 때). 초안이 바뀔 때마다 이 값도 바뀝니다. 위의 첫 번째 요청의 경우:
[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":""}]→ cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4. 이 문자열은 직접 만드세요(JSON 라이브러리의 키 순서나 이스케이프는 필요 없습니다. 이 필드들에는 이스케이프가 필요한 문자가 들어갈 수 없습니다). 서명자가 보는 지문은 contentHash의 처음 16개 16진수 문자입니다(여기서는 cc43baacd7df98ef). 이 값들로 무엇을 해야 하는지는 8절에서 설명합니다.
6.3 GET /drafts?since=<cursor>&limit=<n>
커서 이후에 있는 이 키의 초안을 updatedAt, 그다음 draftId 순서로 돌려줍니다(since가 없으면 보관 중인 가장 오래된 것부터). limit은 1~100이며 기본값은 50입니다.
{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}초안의 updatedAt은 초안의 상태나 줄이 바뀔 때마다 갱신되므로, 마지막 nextCursor로 폴링하면 모든 변경을 볼 수 있습니다. 빈 페이지는 보낸 커서를 그대로 돌려줍니다. 그 커서를 계속 사용하세요. 읽을 수 없는 커서는 400 invalid_request입니다.
6.4 GET /drafts/{draftId}
200 {"draft":<draft>}. 다른 키의 초안(같은 멀티시그라도)이나 더 이상 보관되지 않는 초안은 404 not_found입니다.
6.5 DELETE /drafts/{draftId}
아무도 시작하지 않은 초안을 철회합니다. 상태가 submitted일 때만 가능하며, 모든 줄이 withdrawn이 되고 200 {"draft":<draft>}를 돌려줍니다. 이미 withdrawn이면 다시 200입니다. 그 밖에는 409 not_withdrawable이며 details.status가 함께 옵니다. 서명자가 초안을 시작한 뒤에는 남은 줄을 거절해 달라고 서명자에게 요청하세요.
7. 상태
7.1 초안 status
| 상태 | 의미 |
|---|---|
submitted | 아직 아무도 시작하지 않았습니다. 봇이 초안을 변경하거나(6.2절) 철회할 수 있는(6.5절) 것은 이때뿐입니다 |
started | 서명자가 자신의 휴대폰에서 시작했습니다(처음 시작한 시각은 startedAt). 예를 들어 휴대폰이 도중에 멈춘 경우 서명자가 초안을 열어 다시 시작할 수 있으며, 상태는 계속 started입니다 |
rejected | 서명자가 웹 콘솔이나 휴대폰에서 거절했거나(시작 전이든 후든), 아무도 시작하기 전에 키가 취소되었습니다. 사유는 rejection에 있습니다 |
withdrawn | 봇이 철회했습니다 |
expired | 7일 안에 아무도 시작하지 않았습니다 |
Ownbit는 확실히 아는 것, 즉 서명자가 자신의 휴대폰에서 초안을 시작했다는 사실만 알려 줍니다. 그 뒤에 어떤 지급이 이루어졌는지는 알지 못하므로, started 초안은 전액 지급되었을 수도, 일부만 지급되었을 수도, 전혀 지급되지 않았을 수도 있습니다. 지급은 멀티시그의 거래이므로 8절에 따라 확인하고, 지급되지 않았다고 서명자가 알려 주지 않는 한 시작된 초안의 줄을 다시 제출하지 마세요.
7.2 줄 state
줄의 state는 항상 그 초안의 상태와 같습니다. 1단계에서 Ownbit는 각 줄의 거래를 추적하지 않습니다.
| 상태 | 의미 |
|---|---|
pending | 초안이 submitted 상태입니다 |
started | 초안이 started 상태입니다 |
rejected, withdrawn, expired | 초안의 상태를 따릅니다 |
7.3 보관 기간
아무도 시작하지 않은 초안은 7일 뒤 만료됩니다. 시작된 초안은 서명자가 거절할 때까지 started 상태로 남습니다. 거절, 철회, 만료된 초안은 끝난 뒤 30일 동안, 시작된 초안은 마지막 변경 후 30일 동안 보관되었다가 삭제됩니다(이후 GET은 404를 응답하고, 같은 clientRequestId는 365일 더 410을 응답합니다).
8. 지급 내용 확인
Ownbit는 여러분의 목록을 봇에서 서명자의 화면까지 전달합니다. 그 과정에서 아무것도 바뀌지 않았는지 확인하려면:
clientRequestId와 지문(contentHash의 처음 16개 16진수 문자)을 여러분의 승인 채널에서 승인된 지급 목록 옆에 표시하세요. 초안을 변경하면 지문도 새로 바뀌므로 최신 지문을 표시하세요. 서명자는 웹 콘솔에서 두 값을 보는데, 이는 서명자의 브라우저가 곧 시작할 줄로부터 다시 계산한 값이며, 서명자는 이를 여러분의 기록과 비교하라는 안내를 받습니다. 이 비교는 승인 기록에 두 값이 있어야만 가능합니다.- 조회한 모든 초안의 줄로부터
contentHash를 다시 계산하고(6.2.3절), 초안의 최신 리비전에 대해 계산한 값과 비교하세요. - 멀티시그의 지급을 직접 체인에서 확인하세요. 1단계에서 Ownbit는 각 줄의 거래를 알려 주지 않습니다. 초안이
started가 되면 그 줄을 멀티시그 주소(whoami의multisig.address)에서 나간 거래와 비교하세요. 모든 지급의 수신자, 금액, 토큰이 여러분의 줄 중 하나와 같아야 하고, 각 줄은 최대 한 번만 지급되어야 합니다. repeated를 주시하세요: 최근 다른 초안의 줄과 같은 줄은 서명자에게 표시되므로, 여러분의 시스템에서도 표시되어야 합니다.- 기업용 멀티시그라면 멤버에게 화이트리스트와 일일 한도를 켜 달라고 요청하세요. 그러면 잘못된 초안이라도 모르는 주소로 지급하거나 한도를 넘게 지급할 수 없습니다. 다른 멀티시그에는 화이트리스트가 없으므로 서명자의 확인이 유일한 검사입니다.
9. 오류
모든 오류는 다음 본문을 가집니다.
{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}message는 사람을 위한 고정된 영어 문장입니다. 프로그램은 code와 details를 기준으로 작성하세요. 메시지에는 여러분이 보낸 입력이 절대 그대로 담기지 않습니다.
| HTTP | code | 경우 |
|---|---|---|
| 400 | invalid_request | JSON이 아님, 잘못된 타입, 알 수 없는 필드, 잘못된 clientRequestId, 줄이 없거나 500개 초과, 잘못된 커서나 limit, 10초 안에 도착하지 않은 요청 본문 |
| 401 | unauthorized | 키와 관련된 모든 문제(5절) |
| 403 | forbidden | 호출에 필요한 권한이 없는 유효한 키 |
| 403 | https_required | 요청이 HTTPS로 오지 않음(그 요청에 실린 키를 취소하세요) |
| 404 | not_found | 알 수 없는 경로. 이 키의 것이 아니거나 더 이상 보관되지 않는 초안 |
| 405 | method_not_allowed | 경로가 받지 않는 메서드(OPTIONS 포함) |
| 409 | idempotency_conflict | 6.2절 |
| 409 | not_editable | 6.2절(details.status) |
| 409 | not_withdrawable | 6.5절(details.status) |
| 410 | gone | 초안이 삭제된 clientRequestId |
| 413 | too_large | 256 KiB를 넘는 본문 |
| 415 | unsupported_media_type | JSON이 아닌 POST |
| 422 | invalid_lines | 6.2절(details.errors) |
| 429 | rate_limited, daily_limit | 한도(10절). Retry-After, details.scope, details.limit, details.retryAfter가 함께 옵니다 |
| 500 | internal | Ownbit 쪽 오류. 나중에 재시도하세요 |
| 503 | unavailable | API가 꺼져 있거나 지금 응답할 수 없음. 바쁠 때는 details.scope api_busy와 Retry-After가 함께 옵니다 |
429(scope edge)나 413이 API 앞단의 보호 계층에서 나온 경우에도 같은 형태이며, "requestId":null입니다.
10. 속도 제한과 일일 한도
10.1 한도
| 한도 | 값 | details.scope | code |
|---|---|---|---|
| 한 주소의 요청, 버스트 | 초당 20회(버스트 최대 40회), 동시 연결 20개 | edge | rate_limited |
| 키당 호출 | 초당 10회 | key_second | rate_limited |
| 키당 호출 | 분당 300회 | key_minute | rate_limited |
키당 POST /drafts | 시간당 60회 | key_submit_hour | rate_limited |
| 키당 동시 진행 중인 호출 | 2 | key_concurrent | rate_limited |
| 멀티시그당 동시 진행 중인 호출(모든 키 합산) | 4 | multisig_concurrent | rate_limited |
| 주소당 호출(유효한 키) | 분당 600회. 허용 목록이 비어 있지 않고 그 주소를 포함하는 키는 절대 거부하지 않음 | ip_minute | rate_limited |
| 키당 호출 | 하루 10,000회 | key_day | rate_limited |
| 멀티시그당 호출(모든 키 합산) | 하루 20,000회 | multisig_day | rate_limited |
| 주소당 호출(유효한 키) | 하루 50,000회. 허용 목록이 비어 있지 않고 그 주소를 포함하는 키는 절대 거부하지 않음 | ip_day | rate_limited |
| 주소당 호출(유효한 키), 절대 상한 | 하루 200,000회, 모든 키에 적용 | ip_day(details.limit 200000) | rate_limited |
| 주소당 실패한 호출 | 분당 20회. 넘으면 주소가 10분 동안 보류됨 | ip_failures | rate_limited |
| 주소당 실패한 호출 | 하루 200회. 넘으면 주소가 24시간 동안 차단됨 | ip_blocked | rate_limited |
| 네트워크(/24)당 실패한 호출 | 하루 1,000회. 넘으면 네트워크가 24시간 동안 차단됨 | net_blocked | rate_limited |
| 키당 지급 줄 | 임의의 24시간 동안 키 자체의 한도(1~10,000, 기본값 1,000) | key_lines_24h | daily_limit |
| 멀티시그당 지급 줄 | 임의의 24시간 동안 10,000 | multisig_lines_24h | daily_limit |
| API 전체 과부하 | (서비스 보호용) | api_busy(HTTP 503) | unavailable |
- 하루는 UTC 기준 달력 날짜입니다: 호출 한도와 실패 한도는 00:00 UTC(베이징 시각 08:00)에 다시 시작됩니다. 두 가지 줄 수 한도는 롤링 방식으로, 임의의 24시간을 기준으로 합니다.
- 집계 대상. 유효한 키로 한 모든 호출은 키, 멀티시그, 주소 한도에 집계됩니다. 조회 호출도, 키가 수락된 뒤 거부된 호출(
403,404,409,422, 또는 줄 수 한도의429)도, 반복된POST /drafts도 포함됩니다. 속도 제한이나 한도로 거부된 호출은 어디에도 집계되지 않으므로Retry-After만큼 기다리면 항상 통합니다. 키가 거부된(401) 호출은 그 주소와 네트워크의 실패한 호출에만 집계됩니다. - 보류되거나 차단된 주소나 네트워크(10분 보류 또는 24시간 차단)도 유효하고 허용 목록이 그 주소를 허용하는 키(빈 허용 목록은 모두 허용)에는 계속 응답합니다. 그곳에서는 잘못된 키로 한 호출과, 허용 목록이 그 주소를 허용하지 않는 키의 호출만 거부됩니다. 따라서 유효한 키는 같은 주소에서 일어난 다른 사람의 실패 때문에 막히는 일이 없습니다.
- 주소당 한도는 그 주소에서 호출하는 모두가 공유합니다. 허용 목록이 비어 있지 않고 그 주소를 포함하는 키는 분당 600회나 하루 50,000회 한도로 거부되지 않지만, 버스트 한도(초당 20회)와 절대 상한(하루 200,000회)은 그 주소의 모든 호출자를 집계합니다. 따라서 공유 NAT, CI 러너, 클라우드 egress에서는 다른 사람 때문에 호출이 느려질 수 있으며,
429가 scopeip_minute나ip_day로 오면 같은 주소의 다른 호출자가 많다는 뜻입니다. 전용 발신 주소를 사용하세요.
10.2 응답
한도에 걸리면 429(또는 503: api_busy일 때)로 다음과 같이 응답합니다.
{"error":{"code":"rate_limited","message":"Daily call limit of this key reached",
"details":{"scope":"key_day","limit":10000,"retryAfter":31260}},"requestId":"req_0123456789abcdef"}그리고 헤더 Retry-After: 31260: 기다려야 할 초 단위 정수(최소 1)입니다. 이 값은 윈도우, 보류, 차단이 끝날 때까지입니다. 일일 호출 한도는 00:00 UTC까지, 줄 수 한도는 가장 오래된 줄이 충분히 24시간 밖으로 나갈 때까지(최소 60초), edge와 두 가지 _concurrent scope는 1, api_busy는 1초에서 약 90초 사이이며 거부된 클라이언트가 한꺼번에 돌아오지 않도록 무작위 요소가 들어갑니다. 여러 한도가 동시에 거부하면 응답은 대기 시간이 가장 긴 한도를 알려 줍니다. details.limit은 그 한도의 값입니다(api_busy에서는 주지 않음). 429 중 Retry-After가 없는 유일한 경우는 줄 수 한도 안에 결코 들어갈 수 없는 초안으로, details.neverFits가 true이고 details.retryAfter가 null입니다(6.2절).
메시지: Too many requests from this address (edge, ip_minute), Too many failed requests from this address (ip_failures), This address is blocked after too many failed requests (ip_blocked), This network is blocked after too many failed requests (net_blocked), Too many requests for this key (key_second, key_minute), Too many concurrent requests for this key (key_concurrent), Too many concurrent requests for this multisig (multisig_concurrent), Too many drafts submitted with this key in the last hour (key_submit_hour), Daily call limit of this key reached (key_day), Daily call limit of this multisig reached (multisig_day), Daily call limit of this address reached (ip_day), Line limit of this key for 24 hours reached (key_lines_24h), Line limit of this multisig for 24 hours reached (multisig_lines_24h), The API is busy, retry later (api_busy).
10.3 헤더
키가 수락된 호출에 대한 모든 응답(성공, 그 이후의 오류, 그리고 그 호출의 429)에는 다음이 붙습니다.
| 헤더 | 값 |
|---|---|
X-RateLimit-Limit | 키의 일일 호출 한도(10000) |
X-RateLimit-Remaining | 이번 호출 후 오늘 남은 횟수: 키와 그 멀티시그에 남은 횟수 중 작은 값 |
X-RateLimit-Reset | 다음 00:00 UTC, Unix 초 단위(2026-11-17 기준: 1794960000) |
401, 429(edge, ip_failures, ip_blocked, net_blocked), 그리고 503에는 이 헤더가 하나도 붙지 않습니다. GET /whoami는 같은 카운트를 본문에 담아 줍니다(callsToday, multisigCallsToday, callsResetAt).
10.4 바람직한 봇의 폴링과 백오프
GET /drafts?since=<last nextCursor>를 30초마다, 키당 폴러 하나로 폴링하세요. 하루 2,880회 호출입니다. 봇의 여러 인스턴스가 키 하나를 공유한다면 그중 하나만 폴링하고 읽은 내용을 공유하게 하세요. 마지막nextCursor는 재시작해도 유지하세요. 빈 페이지는 커서를 바꾸지 않고 돌려줍니다.hasMore가true이면 다음 페이지를 바로 읽으세요.- 예산이 허용하는 것보다 빠르게 폴링하지 마세요: 폴링이 하루 호출의 절반 이상을 쓰지 않도록 최대 86,400 × 2 /
X-RateLimit-Limit초에 한 번(기본값 10,000이면 17.3초)입니다. 10초마다 폴링하면 그것만으로 8,640회를 써서 나머지 용도로는 약 1,300회만 남습니다. 한 키로 그렇게 하는 봇 인스턴스가 둘이면 하루가 끝나기 전에 거부됩니다. - 초안 하나는 그 줄이 필요할 때만 조회하세요. 즉 목록에서 그 초안의
updatedAt이 바뀌었을 때만, 그리고 초안당 1분에 최대 한 번입니다. 초안마다 따로 폴링하지 마세요. X-RateLimit-Remaining을 주시하세요.X-RateLimit-Limit의 10분의 1 아래로 떨어지면 폴링 빈도를 줄이세요. 이 값은 멀티시그의 다른 키와 공유된다는 점을 기억하세요.429를 받으면:Retry-After초에 짧은 무작위 지연을 더해 기다린 뒤 재시도하세요. 그보다 일찍 재시도하지 마세요. 응답은 같습니다.key_day나multisig_day라면 커서를 유지하고X-RateLimit-Reset이후에 재개하세요.503을 받으면:Retry-After가 있으면 그 값에 0~30초의 무작위 시간을 더해 기다리고, 없으면 30초부터 최대 10분까지 지수적으로 백오프하세요.- 네트워크 오류나
500이POST /drafts중에 나면: 위와 같이 백오프한 뒤 같은clientRequestId로 같은 요청을 다시 보내세요(6.2.2절). 401을 받으면: 그 키 사용을 멈추고 사람에게 알리세요. 거부된 키로 재시도해도 소용없으며, 하루 200회를 넘는 실패는 모든 잘못된 키에 대해 여러분의 주소를 24시간 동안 차단합니다(유효한 키는 그 주소에서도 계속 작동합니다, 10.1절).- UTC 자정을 대비하세요: 하루 호출을 다 쓴 키나 멀티시그는 00:00 UTC까지 거부됩니다. 그때 정각에 바로 재개하지 말고 0~30초의 무작위 시간 뒤에 재개하세요.
11. 보안 권장 사항
- HTTPS만 사용하세요. 키를 평문 HTTP로 절대 보내지 마세요. 그런 일이 있었다면 키를 취소하세요. 서버 인증서는 평소처럼 검증하세요.
- 키는 서버에 보관하세요. 비밀 저장소에 두고, 브라우저, 모바일 앱, 저장소, 로그, URL, 티켓, 채팅 메시지에는 절대 두지 마세요. Ownbit는 여러분에게 키를 절대 요구하지 않습니다.
- 모든 키에 IPv4 허용 목록을 설정하세요. 여러분 서버의 고정 발신 주소로 구성합니다. 그러면 유출된 키를 다른 곳에서 쓸 수 없으므로 초안을 제출할 수도, 멀티시그의 일일 호출을 소모할 수도 없습니다. 공유 NAT나 클라우드 egress보다 전용 발신 주소를 쓰세요. 보류되거나 차단된 주소도 유효한 키에는 계속 응답하고, 허용 목록이 그 주소를 포함하는 키는 주소당 분당 600회나 하루 50,000회 한도로 거부되지 않지만, 버스트 한도와 하루 200,000회는 그 주소의 모두가 공유합니다(10.1절).
- 시스템마다 키 하나를 쓰고, 어느 시스템인지 알 수 있는 이름을 붙이세요. 멀티시그당 키는 최대 5개입니다.
- 만료 전이나 조금이라도 의심스러울 때 교체하세요: 멤버에게 새 키를 만들게 하고, 봇을 새 키로 바꾼 다음, 이전 키를 취소하세요. 새 키는 새
clientRequestId를 사용해야 합니다(6.2.2절). - 유출되면 즉시 취소하세요. 웹 콘솔이나 Ownbit 앱에서 할 수 있습니다. 취소하면 그 키의 초안 중 아무도 시작하지 않은 것은 거절됩니다. 유출된 키가 오늘 멀티시그의 호출을 다 써 버렸다면 교체한 키도 00:00 UTC까지 그 한도를 공유합니다. Ownbit 지원팀에 문의하면 그날 그 멀티시그의 한도를 올려 줄 수 있습니다.
- 취소된 키를 쓰는 작업은 끄세요: 그 실패는 여러분의 주소에 집계됩니다.
- 승인 채널에
clientRequestId와 지문을 표시하고,contentHash와 체인상의 멀티시그 지급을 확인하세요(8절). - 모든 줄에
symbol을 보내세요. - API에서 받은 텍스트는 데이터로 취급하세요. 로그와 대시보드에서 HTML이나 명령으로 다루지 마세요.
12. 1단계에 없는 기능
웹훅, 줄별 거래 결과(줄의 거래 ID, 해시, 서명, 오류), 다른 체인의 멀티시그와 다른 토큰, IPv6 접속과 IPv6 허용 목록 항목, 사용자가 정하는 키별 호출 한도, 여러분 자신의 키로 서명한 초안. 이 중 필요한 것이 있으면 Ownbit에 문의하세요.
마지막 업데이트:
Ownbit 다운로드
앱을 설치한 다음 필요에 맞게 콜드월렛이나 멀티시그를 설정하세요.