Bitcoin RPC (curl) 통합 가이드

Docker로 실행 중인 Bitcoin Core 노드의 RPC 설정/보안/외부접속과 curl 호출 예시를 하나로 통합한 문서입니다.

0) 현재 구성 빠른 요약 (docker-compose.yml 기준)

RPC 포트: 8332
P2P 포트: 8333
권장 보안 기본값: RPC는 127.0.0.1로만 노출 + rpcallowip=127.0.0.1
외부 RPC가 필요할 때: ports: "8332:8332"로 노출하되, 반드시
- rpcallowip를 특정 IP/CIDR로 제한
- UFW/보안그룹에서 해당 IP만 8332 허용

0-1) (중요) ping은 되는데 8332만 안 열릴 때: 원인/점검 순서

서버(예: 162.19.222.84)가 ping으로는 살아있는데 8332 접근이 안 되면, 보통 아래 중 하나(또는 복수)에서 막힌 상태입니다.

Docker 포트 매핑(가장 흔함)
서버 방화벽(UFW/iptables)
클라우드/IDC 네트워크 방화벽(예: OVH 네트워크 방화벽)

즉시 점검/해결 순서(서버에 SSH 접속 후 그대로 실행)

1) Docker 포트 매핑 확인(가장 먼저!)

docker ps | grep bitcoin

정상 기대(예시): 0.0.0.0:8332->8332/tcp 가 보여야 외부에서 접근 가능합니다.

CONTAINER ID   IMAGE          ...   PORTS
abc123         docker_bitcoind ...  0.0.0.0:8332->8332/tcp, 0.0.0.0:8333->8333/tcp

문제 패턴

127.0.0.1:8332->8332/tcp 로만 보임 → 외부 접근 불가
8332 매핑 자체가 없음 → 외부 접근 불가

해결(Compose 사용 시 권장): chains/bitcoin/docker/docker-compose.yml에서 아래처럼 설정 후 재시작

ports:
  - "8333:8333"
  - "8332:8332"  # 0.0.0.0:8332 의미(외부 노출)

cd ~/blockchain-node-guides/chains/bitcoin/docker
sudo docker-compose down
sudo docker-compose up -d

2) 서버 방화벽(UFW/iptables) 확인

sudo ufw status || true
sudo ss -tlnp | egrep ':(8332|8333)\\b' || true

외부 RPC를 열었다면 허용 IP만 8332를 열어야 합니다.

sudo ufw allow from <YOUR_CLIENT_IP> to any port 8332 proto tcp

3) OVH(또는 클라우드) 네트워크 방화벽 확인

서버 내부(UFW)에서 열어도, OVH 네트워크 방화벽에서 8332가 막혀 있으면 외부에서 계속 안 열립니다. OVH 콘솔에서 8332/tcp를 허용 IP로만 열어주세요.

1) 가장 간단한 호출 템플릿

A. 로컬(서버 내부)에서 호출

RPC_URL="http://127.0.0.1:8332"
RPC_USER="bitcoin"
RPC_PASS="<RPC_PASSWORD>"

curl -sS -X POST \
  -H "Content-Type: application/json" \
  --user "${RPC_USER}:${RPC_PASS}" \
  --data '{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}' \
  "${RPC_URL}"

B. 편의 함수(권장)

btc_rpc () {
  local method="$1"; shift
  local params="${1:-[]}"
  curl -sS -X POST \
    -H "Content-Type: application/json" \
    --user "${RPC_USER}:${RPC_PASS}" \
    --data "{\"jsonrpc\":\"2.0\",\"method\":\"${method}\",\"params\":${params},\"id\":1}" \
    "${RPC_URL}"
}

# 예시
btc_rpc getblockcount
btc_rpc getblockhash "[800000]"

2) 자주 쓰는 RPC 메서드 목록 (curl 예시 포함)

노드/동기화 상태

btc_rpc getblockchaininfo
btc_rpc getnetworkinfo
btc_rpc getconnectioncount
btc_rpc getmempoolinfo

블록 조회

# 최신 높이
btc_rpc getblockcount

# 특정 높이의 블록 해시
btc_rpc getblockhash "[800000]"

# 블록 상세(verbosity=1)
BLOCK_HASH=$(btc_rpc getblockhash "[800000]" | jq -r '.result')
btc_rpc getblock "[\"${BLOCK_HASH}\", 1]"

트랜잭션 조회 / 브로드캐스팅

getrawtransaction은 보통 txindex=1이 필요합니다(이미 켜두는 구성이 많음).

# 트랜잭션 조회(verbosity=1)
btc_rpc getrawtransaction "[\"<TXID>\", 1]"

# 전파 전 검증
btc_rpc testmempoolaccept "[[\"<RAW_TX_HEX>\"]]"

# 전파
btc_rpc sendrawtransaction "[\"<RAW_TX_HEX>\"]"

3) 외부에서 RPC 접근 허용(권장 방식)

3-1) docker-compose 포트 노출

외부에서 접근해야 하면 아래처럼 호스트 8332를 외부에 노출합니다.

ports:
  - "8333:8333"
  - "8332:8332"   # 외부 접근이 필요할 때만

3-2) rpcallowip를 “접근할 IP만” 허용

command:
  - -rpcbind=0.0.0.0
  - -rpcallowip=127.0.0.1
  - -rpcallowip=172.21.0.0/16     # Docker 네트워크(호스트→컨테이너 포워딩 소스가 이 대역일 수 있음)
  - -rpcallowip=<YOUR_CLIENT_IP>  # 예: 203.0.113.10
  # 또는 사설망 대역
  # - -rpcallowip=192.168.0.0/24

절대 권장하지 않음: -rpcallowip=0.0.0.0/0 (인터넷 전체에 RPC 오픈)

3-3) 방화벽(UFW)도 반드시 제한

# 예: 특정 클라이언트 IP만 8332 허용
sudo ufw allow from <YOUR_CLIENT_IP> to any port 8332 proto tcp

# P2P는 일반적으로 전체 허용(환경에 따라)
sudo ufw allow 8333/tcp
sudo ufw allow 8333/udp

sudo ufw status

3-4) 외부에서 호출 예시

RPC_URL="http://<SERVER_PUBLIC_IP>:8332"
RPC_USER="bitcoin"
RPC_PASS="<RPC_PASSWORD>"

btc_rpc getblockchaininfo | jq '.result | {chain, blocks, headers, verificationprogress}'

4) “호스트에서는 안 되고 컨테이너에서는 되는” 경우(핵심)

원인 요약:

호스트에서 http://127.0.0.1:8332로 호출하더라도, bitcoind가 보는 소스 IP가 Docker 게이트웨이(예: 172.21.0.1)로 잡힐 수 있습니다.
이때 rpcallowip=127.0.0.1만 있으면 호스트 호출이 거부됩니다.

해결:

rpcallowip에 Docker 네트워크 CIDR(예: 172.21.0.0/16)를 추가

5) 문제 해결(증상별)

5-1) Connection refused

체크 순서:

포트가 실제로 열려있는지
docker-compose 포트 매핑이 올바른지
방화벽이 막는지

sudo ss -tlnp | grep 8332
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep bitcoin
sudo ufw status

추가로 유용한 확인:

# (외부 클라이언트에서) 포트 레벨 연결 확인
nc -zv <SERVER_PUBLIC_IP> 8332

# (외부 클라이언트 IP 확인)
curl ifconfig.me

5-2) Authorization failed / incorrect password attempt