지갑 API 사용법

지갑은 API 게이트웨이를 통해서만 체인에 접근합니다 (검증인 노드는 노출되지 않습니다). 지갑이 서명하고, 체인이 검증·실행합니다. 조회는 인덱서·노드 REST를 경유합니다.

1. 진입점

게이트웨이 (외부)https://wallet-api.sjo.mypgtest.com (개발: http://<호스트>:26670)

인증지갑 개인키 서명 (비수탁)

체인 IDsjo-dev-1 (개발) / sjo-mainnet-1 (운영)

Bech32 prefixsjo

2. 서명 Tx 전달 — POST /tx

지갑이 개인키로 서명한 Tx 바이트를 게이트웨이에 넘기면 풀노드를 통해 체인에 브로드캐스트됩니다.

요청

{
  "signed_tx": "<base64 서명된 Tx>",
  "signature": "<base64 지갑 개인키 서명>"
}

응답 (200)

{
  "tx_hash": "0x1234...",
  "height": 12345,
  "status": "success"
}

3. 조회 프록시 — GET /query/{path}

조회는 상태를 변경하지 않습니다. 응답은 인덱서 또는 노드 REST의 JSON을 그대로 반환합니다.

경로	설명
`/query/blocks/{height}`	블록 조회
`/query/tx/{hash}`	트랜잭션 조회
`/query/accounts/{address}`	계정(잔고) 조회
`/query/seed/coverage`	분산 시드 커버리지

4. 모듈 쿼리 (지갑 백엔드용)

경로	설명
`/query/cosmos/bank/v1beta1/balances/{addr}`	실시간 잔고 (usjo)
`/query/sjo/supply/v1/rate`	공급 조절 배율 (dev-05)
`/query/sjo/mining/v1/base_reward/{devices}`	기본 보상 (dev-06)
`/query/sjo/mining/v1/active_devices`	활성 디바이스 수
`/query/sjo/mining/v1/adjustment_multiplier`	조정 배율
`/query/sjo/mining/v1/reward_status/{id}`	리워드 상태
`/query/sjo/mining/v1/last_reward_date`	마지막 지급 날짜
`/query/qrlock/v1/locks/{id}/exists`	QR 잠금 존재 여부 (dev-03)
`/query/qrlock/v1/locks/{id}`	QR 잠금 조회
`/query/qrlock/v1/locks`	QR 잠금 목록

5. 리워드 요청 — POST /reward

지갑 백엔드가 계산한 데일리 리워드 배치를 체인으로 전달합니다. 허용 백엔드 주소만 가능합니다.

{
  "signer": "sjo1...허용백엔드",
  "batch": {
    "utc_date": "2026-09-02",
    "items": [{ "request_id": "r1", "recipient": "sjo1...", "amount_usjo": "100" }],
    "json_auth": "<base64 서명>"
  }
}

미허가 주소 → 403 unauthorized signer

6. 오류 코드

코드	의미
400	요청 형식 오류 / 누락 필드
401	리워드 서명 검증 실패
403	미허가 signer (리워드)
422	체인이 Tx 를 수용하지 않음 (code 18 등)
502	인덱서/노드 조회 소스 연결 실패
404	조회 대상 없음

7. 예시 (curl)

잔고 조회

curl https://wallet-api.sjo.mypgtest.com/query/cosmos/bank/v1beta1/balances/sjo1cm3rpp0wxl6sudzzt4fp8qy4aeszs5ajq6j7qr

서명 Tx 전달

curl -X POST https://wallet-api.sjo.mypgtest.com/tx \
  -H "Content-Type: application/json" \
  -d '{"signed_tx":"<base64>","signature":"<base64>"}'

QR 잠금 존재 확인

curl https://wallet-api.sjo.mypgtest.com/query/qrlock/v1/locks/42/exists

8. Go 클라이언트

구현: sjo/wallet/internal/client — BroadcastTx, AccountBalance, MiningBaseReward/ActiveDevices/Multiplier/RewardStatus/LastRewardDate, SupplyRate, QRLockExists/QRLock/QRLocks, RequestReward.

참조 문서: sjo/wallet/docs/wallet-interface.md · doc/dev/dev-21-wallet-interface.md