plug
plug
문서 버전: v1.3 · 최종 업데이트: 2026-02-16 (KST)

plug 사용자 문서

plug는 Plumise RPC를 위한 인증 게이트웨이입니다.
공개 RPC URL을 그대로 노출하지 않고, API 키·사용량·한도(쿼터)를 운영할 수 있도록 설계되었습니다.

1. 서비스 개요

plug가 하는 일

  • API 키 기반 인증
  • 키 단위 요청량 집계와 월간 한도 차감
  • 키 차단/폐기/삭제 및 대시보드 관리
  • HTTP JSON-RPC + WebSocket 프록시

plug가 하지 않는 일

  • 사용자의 가상자산 보관/수탁
  • 사용자 대신 매매·교환·중개
  • 사용자 대신 체인 전송 실행

2. 시작 전 체크리스트

  1. plug.plumise.com 로그인 가능 여부 확인
  2. API 키 생성 직후 안전한 비밀 저장소에 보관
  3. 기존 Dapp/서버의 RPC URL 치환 대상 목록 작성
  4. 장애 대비 fallback RPC와 재시도 정책 점검

3. 엔드포인트 매트릭스

목적프로토콜URL 패턴
Mainnet 호출HTTPShttps://plug.plumise.com/rpc/<API_KEY>
Testnet 호출HTTPShttps://plug.plumise.com/rpc/testnet/<API_KEY>
Mainnet 구독WSSwss://plug.plumise.com/ws/<API_KEY>
Testnet 구독WSSwss://plug.plumise.com/ws/testnet/<API_KEY>
헤더 인증 호출HTTPShttps://plug.plumise.com/rpc + Authorization 헤더

4. 인증 방식

A. URL 경로 인증 (브라우저 Dapp 권장)

  • 경로에 키를 포함: /rpc/<API_KEY>
  • 장점: 설정 단순
  • 주의: URL 로그/에러 리포팅에 키가 남지 않도록 마스킹 필요

B. 헤더 인증 (서버/백엔드 권장)

  • Authorization: Bearer <API_KEY>
  • 또는 x-plug-key: <API_KEY>
  • 장점: URL 노출 방지

5. 첫 호출 예제

curl -sS https://plug.plumise.com/rpc/<API_KEY> \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

curl -sS https://plug.plumise.com/rpc \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <API_KEY>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

6. 클라이언트 통합

viem

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({
  chain: mainnet,
  transport: http("https://plug.plumise.com/rpc/<API_KEY>")
});

ethers (HTTP)

import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider("https://plug.plumise.com/rpc/<API_KEY>");

ethers (WebSocket)

import { WebSocketProvider } from "ethers";

const ws = new WebSocketProvider("wss://plug.plumise.com/ws/<API_KEY>");
ws.on("block", (n) => console.log("block", n));

web3.py

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("https://plug.plumise.com/rpc/<API_KEY>"))
print(w3.eth.chain_id)

7. WebSocket 운영 가이드

연결 정책

  • 연결이 유휴 상태로 오래 유지되면 서버/네트워크 장비에서 정리될 수 있음
  • 구독 기반 트래픽 또는 주기적 ping으로 세션 유지 권장

재연결 전략

  1. 지수 백오프(예: 1s, 2s, 4s, 최대 30s)
  2. 재연결 후 구독 목록 재등록
  3. 최근 블록 기준 데이터 누락 보정

8. API 키 라이프사이클

생성

  • 키는 생성 직후 1회만 전체 값이 표시됨
  • 분실 시 재조회가 아니라 새 키 발급 후 교체 필요

운영

  • 서비스별/환경별 분리 권장: prod-backend, wallet-web, indexer 등
  • 키 노출 사고가 의심되면 즉시 차단 또는 폐기

교체(권장 절차)

  1. 새 키 생성
  2. 애플리케이션 설정 반영
  3. 정상 호출 확인
  4. 구 키 폐기

9. 쿼터와 과금

집계 원칙

  • 월간 쿼터는 API 키 단위로 차감
  • 쿼터 초과 시 해당 키 요청은 HTTP 429로 차단
  • 집계 시간 기준은 UTC

운영 팁

  • 트래픽 버스트가 있는 키는 별도로 분리
  • 중요 워크로드는 별도 키로 격리해 장애 전파 최소화

10. 오류 코드와 대응

HTTPJSON-RPC의미즉시 조치
401-인증 실패(키 누락/오류)키 전달 방식/오타 확인
403-32003계정 또는 키 차단 상태관리자에서 차단 해제
429-32005월간 쿼터 초과플랜 업그레이드 또는 주기 갱신 대기
502-32000업스트림 RPC 장애재시도 + fallback RPC 전환

11. 사용자 관점 트러블슈팅

로그인 코드 메일이 안 옴

  1. 스팸함/프로모션함 확인
  2. 최근 1분 내 재요청 여부 확인
  3. 도메인 수신 허용(no-reply@plumise.com) 적용

대시보드에서 키가 안 보임

  1. 올바른 계정인지 확인
  2. 브라우저 쿠키/세션 만료 여부 확인
  3. 새로고침 후에도 동일하면 관리자 문의

갑자기 429가 발생함

  1. 해당 키의 이번 주기 누적 사용량 확인
  2. 다른 서비스가 동일 키를 공유하는지 점검
  3. 고트래픽 서비스용 키 분리

WebSocket이 자주 끊김

  1. Keepalive 미설정 여부 확인
  2. 네트워크 프록시/로드밸런서 timeout 확인
  3. 자동 재연결 + 구독 재등록 로직 점검

12. 보안 운영 체크리스트

  • 키를 코드 저장소에 커밋하지 않기
  • 로그, APM, 에러 리포트에 키 마스킹 적용
  • 키마다 용도와 소유 팀 태깅
  • 정기 키 교체(예: 30~90일)
  • 퇴사/권한 변경 시 즉시 키 회수

13. 운영 FAQ

Q. 키 이름 변경/삭제가 가능한가요?

가능합니다. 단, 삭제는 복구되지 않습니다.

Q. 하나의 키를 여러 서비스가 같이 써도 되나요?

기능적으로는 가능하지만 권장하지 않습니다. 장애 원인 추적과 쿼터 통제를 위해 서비스별 분리를 권장합니다.

Q. 관리자는 제한 없이 사용할 수 있나요?

admin 플랜 계정은 무제한 정책을 사용할 수 있습니다. 내부 서비스 전용으로만 사용하세요.

14. 변경 관리 체크리스트

  1. 새 키 생성 및 저장소 등록
  2. 스테이징에서 RPC 치환 검증
  3. 프로덕션 순차 배포
  4. 메트릭/오류율 모니터링
  5. 구 키 폐기

15. 지원 채널

plug — Production RPC for Plumise