Polymarket 봇 Wallet, Auth, 그리고 Key Management

Polymarket Bot Tutorial · 32개 중 6장

Polymarket bot 인증 및 wallet 설정: proxy wallet vs EOA, SDK를 통한 API key 생성, Gnosis Safe용 sigType 2, key storage best practices, 그리고 Magic에서 Privy로의 migration.

Polymarkets.co.il의 수석 작가 Harley Young 작성. 최종 검토: 2026년 5월.

이 장에서 다루는 내용

Polymarket의 wallet model은 세 가지 구성 요소로 이루어져 있습니다. 주문에 서명하는 externally owned account(EOA), 자금을 보관하는 smart-contract proxy, 그리고 HTTP request를 인증하는 Polymarket CLOB API key입니다. 이 세 가지를 올바르게 연결하는 것은 신규 builder가 Day 1에 가장 흔히 겪는 실패이며, 2025년 8월 Magic Labs에서 Privy로 migration한 이후 더 헷갈리게 되었습니다. 이 장에서는 production code에 필요한 specific environment variables와 signature-type flag까지 포함해, setup 순서대로 각각의 요소를 설명합니다.

• Proxy wallet vs EOA: 어떤 것으로 bot을 돌릴까
• API key 생성하기 (SDK 단계)
• sigType 2와 POLY_FUNDER_ADDRESS (Gnosis Safe)
• Key storage: .env, vault, KMS
• Magic Labs에서 Privy로의 migration
• USDC/pUSD spending 승인하기
• Wallet 복구 및 backup

Proxy wallet vs EOA: 어떤 것으로 bot을 돌릴까

Polymarket은 smart-contract proxy wallet 패턴을 사용합니다. private key에 연결된 주소인 EOA가 transaction과 order에 서명합니다. 결정적 주소에 배포된 Gnosis Safe가 실제 pUSD와 outcome share를 보관합니다. proxy 주소는 Polymarket UI의 "wallet" 패널에 표시되는 주소이고, 서명은 EOA가 합니다.

bot의 경우 항상 EOA(PRIVATE_KEY in env)로 서명하고, CLOB client config에서는 proxy 주소를 POLY_FUNDER_ADDRESS로 참조합니다. funder로 EOA를 사용해 order를 보내면 proxy에 자금이 있어도 "insufficient balance" 오류가 발생합니다.

EOA만으로는 bot을 돌릴 수 없습니다. Polymarket의 web flow는 signup 시 항상 proxy를 생성합니다. CLI에서 polymarket wallet show를 사용해 두 주소를 모두 확인하거나, Polymarket UI의 settings에서 proxy 주소를 확인하세요.

API key 생성하기 (SDK 단계)

CLOB API에는 세 가지 credential이 필요합니다: key, secret, passphrase. 이것들은 wallet private key가 아니라, wallet에 연결된 HMAC-style credential set이며 HTTP request 인증에만 사용됩니다.

SDK로 한 번 생성합니다:

# Python
from py_clob_client.client import ClobClient
c = ClobClient(host="https://clob.polymarket.com", chain_id=137,
               key="<PRIVATE_KEY>", signature_type=2,
               funder="<PROXY_ADDRESS>")
creds = c.create_or_derive_api_creds()
print(creds.api_key, creds.api_secret, creds.api_passphrase)

출력값은 JSON file에 저장하고 bot을 시작할 때마다 불러오세요. 세션마다 다시 생성하지 마세요. API server는 credential set을 cache하며, 자주 회전시키면 rate-limit logic을 건드릴 수 있습니다. 이 credential은 자동으로 만료되지 않습니다. 유출이 의심될 때만 rotate하세요.

sigType 2와 POLY_FUNDER_ADDRESS (Gnosis Safe)

signature_type 인자는 CLOB가 order signature를 검증하는 방식을 제어합니다. 값은 세 가지가 있지만, 실제로 사용되는 것은 두 가지입니다:

• 0 / EOA: EOA가 signer이자 funder인 방식. private key를 직접 imported한 특수한 setup에서 사용됩니다.
• 1 / POLY_PROXY: legacy Magic Labs proxy contract. 대부분의 2025년 이전 account.
• 2 / POLY_GNOSIS_SAFE: 현재 표준. 자금은 Gnosis Safe에 있고, EOA가 서명합니다.

2025년 8월 이후 생성된 account(Privy migration 이후)나, Polymarket UI에서 Gnosis Safe 주소가 보이는 account에는 signature_type=2를 사용하세요. POLY_FUNDER_ADDRESS env var는 EOA가 아니라 Safe 주소여야 합니다. signature_type과 funder type이 맞지 않으면 "insufficient allowance" 또는 "balance: 0"처럼 보이는 order rejection이 조용히 발생합니다. error message는 오해를 불러일으킵니다.

Key storage: .env, vault, KMS

EOA private key를 저장하는 세 가지 합리적인 tier가 있습니다.

1. .env file (단일 머신 개발). 파일은 VPS에 있고, bot은 시작 시 이를 읽으며, key는 host를 벗어나지 않습니다. <$1k wallet에는 충분합니다. chmod 600 .env를 적용하고 repo의 .gitignore에 포함되지 않도록 하세요.
2. Self-hosted vault (HashiCorp Vault, age-encrypted file, 또는 systemd-creds). bot 시작 시 unlock 단계가 추가됩니다. $1k-$10k 범위의 wallet에 적합합니다.
3. Cloud KMS (AWS KMS, GCP KMS). bot이 KMS를 호출해 메모리에서 key를 decrypt하며, key는 disk에 닿지 않습니다. 운영 복잡성 대비 가치가 있는 것은 $10k 이상 또는 multi-bot fleet일 때뿐입니다.

절대 하면 안 되는 것: private key를 git에 commit하기, chat에 붙여넣기, local-only mode 없이 cloud service로 sync되는 password manager에 저장하기. Polymarket EOA가 유출되면 on-chain blast radius는 전체 pUSD balance와 outcome share inventory입니다.

Magic Labs에서 Privy로의 migration

2025년 8월, Polymarket은 주요 embedded-wallet provider를 Magic Labs에서 Privy로 migration했습니다. bot 관점에서의 영향은 작지만 구체적입니다.

migration 이전 account(Magic 통해 생성된 account)는 보통 signature_type=1 (POLY_PROXY)를 사용합니다. migration 이후 account는 signature_type=2 (POLY_GNOSIS_SAFE)를 사용합니다. 일부 사용자는 기존 account를 migration했고, 일부는 원래 account를 유지했습니다. public API만으로는 account가 어떤 type을 사용하는지 알 수 없으며, order 서명을 시도하고 rejection을 확인해야 합니다.

migration은 UI가 funder address를 노출하는 방식도 바꿨습니다. 이전 Polymarket UI flow는 dashboard에 proxy address를 표시했지만, 현재 flow는 account settings 안에 숨겨 둡니다. 계정 생성 시점과 관계없이 polymarket wallet show CLI command가 두 값을 확인하는 가장 깔끔한 방법입니다.

USDC/pUSD spending 승인하기

CLOB가 order match 시 pUSD를 이동하려면, proxy가 Polymarket exchange contract를 spender로 승인해야 합니다. Polymarket UI는 첫 deposit 중에 이 approval을 설정합니다. proxy에 직접 자금을 넣는 bot은 이를 수동으로 설정해야 합니다.

wallet당 한 번 설정해야 하는 세 가지 approval:

1. pUSD (ERC-20) → exchange contract
2. Conditional Tokens (ERC-1155) → exchange contract (share 판매용)
3. Conditional Tokens (ERC-1155) → NegRisk exchange contract (NegRisk share 판매용)

첫 setup 시 CLI에서 polymarket approve를 실행하세요. transaction 비용은 MATIC gas로 몇 센트 수준입니다. polymarket approve check로 확인하세요. 세 가지 모두 "approved"를 반환해야 합니다. 신규 builder가 가장 흔히 겪는 조용한 bug는 NegRisk approval 누락이며, 이는 multi-outcome market에서 share를 팔 때만 실패하고 balance error처럼 보입니다.

Wallet 복구 및 backup

bot의 wallet에는 복구 가능한 두 요소가 있습니다. EOA private key와 Polymarket account password입니다. account password는 web UI 접근을 제어하지만 SDK에는 영향을 주지 않습니다.

bot에서 중요한 것은 EOA private key뿐입니다. 잃어버리면 proxy 안의 모든 것을 잃게 됩니다. cold backup: 종이에 적어 봉투에 밀봉한 뒤 외부 장소에 보관하세요. hot backup: encrypted USB stick. 자신에게 email로 보내지 마세요. cloud storage에 암호화되지 않은 상태로 저장하지 마세요.

Polymarket account password는 원래 signup email을 계속 통제하고 있는 한 Magic Labs / Privy email recovery를 통해 복구할 수 있습니다. 이것은 bot access를 제어하지 않습니다. bot은 EOA private key를 직접 사용하기 때문입니다.

key 유출이 의심되면 즉시 pUSD와 outcome token을 새 wallet으로 withdraw하고, 새 EOA를 생성한 뒤, 새 key로 bot을 redeploy하세요. 유출된 key는 revoke할 수 없으며, 오직 drain될 뿐입니다.

자주 묻는 질문