Polymarket Bot Tutorial · Chương 6/32

Xác thực Polymarket bot và thiết lập wallet: proxy wallets so với EOA, tạo API key qua SDK, sigType 2 cho Gnosis Safe, best practices lưu trữ key, và quá trình migration từ Magic sang Privy.

Bởi Harley Young, biên tập viên chính tại Polymarkets.co.il. Cập nhật lần cuối: tháng 5 năm 2026.

Chương này bao gồm những gì

Mô hình wallet của Polymarket có ba phần: một externally owned account (EOA) dùng để ký order, một smart-contract proxy giữ funds, và Polymarket CLOB API key để xác thực HTTP requests. Thiết lập đúng cả ba là lỗi Day 1 phổ biến nhất với các builder mới, và nó còn trở nên khó hiểu hơn sau đợt migration từ Magic Labs sang Privy vào tháng 8 năm 2025. Chương này sẽ đi qua từng phần theo thứ tự thiết lập, cùng các environment variables cụ thể và signature-type flag mà production code cần.

  • Proxy wallet vs EOA: nên bot với loại nào
  • Tạo API key (các bước SDK)
  • sigType 2 và POLY_FUNDER_ADDRESS (Gnosis Safe)
  • Lưu trữ key: .env, vault, KMS
  • Migration từ Magic Labs sang Privy
  • Phê duyệt chi tiêu USDC/pUSD
  • Khôi phục và sao lưu wallet

Proxy wallet vs EOA: nên bot với loại nào

Polymarket sử dụng mô hình smart-contract proxy wallet. EOA của bạn - địa chỉ gắn với private key - sẽ ký transactions và orders. Một Gnosis Safe được triển khai tại một địa chỉ xác định trước giữ pUSD và outcome shares thực tế. Địa chỉ proxy là thứ hiển thị trong panel "wallet" của Polymarket UI; EOA là thứ ký.

Đối với bot, bạn luôn ký bằng EOA (PRIVATE_KEY trong env) và tham chiếu địa chỉ proxy làm POLY_FUNDER_ADDRESS trong cấu hình CLOB client. Gửi order với EOA làm funder sẽ tạo lỗi "insufficient balance" ngay cả khi proxy đã được nạp tiền.

Bạn không thể bot chỉ với EOA - luồng web của Polymarket luôn tạo một proxy khi đăng ký. Xác nhận cả hai địa chỉ bằng polymarket wallet show từ CLI, hoặc đọc địa chỉ proxy trong phần settings của Polymarket UI.

Tạo API key (các bước SDK)

CLOB API yêu cầu ba credentials: key, secret, passphrase. Đây không phải private key của wallet - mà là một bộ credential kiểu HMAC gắn với wallet của bạn, chỉ dùng để xác thực HTTP requests.

Tạo chúng một lần bằng 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)

Lưu output vào một file JSON và load nó mỗi khi bot khởi động; đừng tạo lại theo từng session - API server có cache bộ credentials, và việc rotate quá thường xuyên có thể kích hoạt logic rate-limit. Các credentials này không tự hết hạn. Chỉ rotate khi bạn nghi ngờ bị lộ.

sigType 2 và POLY_FUNDER_ADDRESS (Gnosis Safe)

Tham số signature_type điều khiển cách CLOB xác thực order signatures của bạn. Có ba giá trị; hai giá trị là thực:

  • 0 / EOA: EOA vừa là signer vừa là funder. Dùng cho các thiết lập bất thường, nơi người dùng import private key trực tiếp.
  • 1 / POLY_PROXY: legacy Magic Labs proxy contract. Hầu hết accounts trước năm 2025.
  • 2 / POLY_GNOSIS_SAFE: chuẩn hiện tại. Funds nằm trong Gnosis Safe, EOA ký.

Hãy dùng signature_type=2 cho mọi account được tạo sau tháng 8 năm 2025 (đợt Privy migration) hoặc bất kỳ account nào bạn thấy địa chỉ Gnosis Safe trong Polymarket UI. Biến env POLY_FUNDER_ADDRESS phải là địa chỉ Safe, không phải EOA. signature_type không khớp với loại funder sẽ âm thầm tạo ra order rejection trông như "insufficient allowance" hoặc "balance: 0" - thông báo lỗi rất dễ gây hiểu nhầm.

Lưu trữ key: .env, vault, KMS

Có ba mức lưu trữ hợp lý cho EOA private key.

  1. File .env (development trên một máy). File nằm trên VPS, bot đọc nó khi khởi động, key không rời khỏi host. Đủ dùng cho wallets <$1k. chmod 600 .env và đảm bảo repo của bạn .gitignore loại trừ nó.
  2. Self-hosted vault (HashiCorp Vault, file mã hóa bằng age, hoặc systemd-creds). Thêm một bước unlock khi bot khởi động. Đáng dùng cho wallets trong khoảng $1k-$10k.
  3. Cloud KMS (AWS KMS, GCP KMS). Bot gọi KMS để giải mã key trong memory; key không bao giờ chạm vào disk. Chỉ đáng với độ phức tạp vận hành này khi trên $10k hoặc với multi-bot fleets.

Điều tuyệt đối không nên làm: commit private key lên git, dán nó vào chat, lưu trong password manager đồng bộ lên cloud services mà không có chế độ local-only. Phạm vi thiệt hại on-chain khi lộ Polymarket EOA là toàn bộ số dư pUSD và inventory outcome shares của bạn.

Migration từ Magic Labs sang Privy

Vào tháng 8 năm 2025, Polymarket đã chuyển primary embedded-wallet provider từ Magic Labs sang Privy. Tác động đối với bot là nhỏ nhưng rất cụ thể.

Accounts trước migration (tạo qua Magic) thường dùng signature_type=1 (POLY_PROXY). Accounts sau migration dùng signature_type=2 (POLY_GNOSIS_SAFE). Một số người dùng đã migrate account cũ; một số giữ nguyên account ban đầu. Không có cách nào từ public API để biết account của bạn dùng loại nào - bạn phải kiểm tra bằng cách thử ký một order và quan sát rejection.

Migration cũng thay đổi cách UI hiển thị địa chỉ funder. Các luồng UI cũ của Polymarket hiển thị địa chỉ proxy trong dashboard; luồng hiện tại giấu nó trong account settings. Lệnh CLI polymarket wallet show là cách rõ ràng nhất để xác nhận cả hai giá trị, bất kể account được tạo khi nào.

Phê duyệt chi tiêu USDC/pUSD

Để CLOB có thể chuyển pUSD của bạn khi order khớp, proxy phải đã phê duyệt các Polymarket exchange contracts làm spender. Polymarket UI thiết lập các approvals này trong lần deposit đầu tiên. Với bots nạp tiền trực tiếp vào proxy, bạn phải thiết lập thủ công.

Có ba approvals cần thiết, mỗi wallet chỉ cần một lần:

  1. pUSD (ERC-20) → exchange contract
  2. Conditional Tokens (ERC-1155) → exchange contract (để bán shares)
  3. Conditional Tokens (ERC-1155) → NegRisk exchange contract (để bán NegRisk shares)

Chạy polymarket approve từ CLI khi thiết lập lần đầu. Transaction tốn vài cent MATIC gas. Kiểm tra bằng polymarket approve check - cả ba đều phải trả về "approved." Lỗi âm thầm phổ biến nhất với builder mới là thiếu NegRisk approval, chỉ thất bại khi bán shares từ multi-outcome markets và trông giống lỗi balance.

Khôi phục và sao lưu wallet

Wallet của bot có hai phần có thể khôi phục: EOA private key, và Polymarket account password (cái này kiểm soát truy cập qua web UI nhưng không qua SDK).

EOA private key là thứ duy nhất quan trọng đối với bot. Mất nó = mất toàn bộ thứ trong proxy. Cold backup: viết ra giấy, niêm phong trong phong bì, lưu ở nơi khác. Hot backup: USB stick được mã hóa. Tuyệt đối không gửi email cho chính mình; tuyệt đối không lưu không mã hóa trong cloud storage.

Polymarket account password có thể khôi phục qua Magic Labs / Privy email recovery miễn là bạn vẫn kiểm soát email đăng ký ban đầu. Nó không kiểm soát quyền truy cập bot - bot dùng trực tiếp EOA private key.

Nếu bạn nghi ngờ key bị lộ: ngay lập tức rút pUSD và outcome tokens sang wallet mới, tạo EOA mới, triển khai lại bot bằng key mới. Key bị lộ không thể revoke; nó chỉ có thể bị rút sạch.

Câu hỏi thường gặp

Tôi có cần một wallet riêng cho bot của mình không?
Nên dùng, rất khuyến nghị. Hãy dùng một EOA mới hoặc một proxy wallet mới được tạo từ email-account, chỉ giữ số vốn bạn đã phân bổ cho bot. Nếu key của bot bị lộ, chỉ quỹ của bot gặp rủi ro - holdings chính của bạn vẫn an toàn.
sigType 2 trong Polymarkets API là gì?
sigType 2 cho biết chữ ký từ Gnosis Safe (proxy wallet), dùng khi bạn đăng nhập bằng email/Google và Polymarket tạo proxy cho bạn. Với sigType 2, biến môi trường POLY_FUNDER_ADDRESS phải là địa chỉ PROXY (địa chỉ hiển thị trong Polymarket UI), không phải EOA bên dưới. Đây là lỗi cấu hình rất phổ biến.
Tôi tạo Polymarket API key như thế nào?
Hãy dùng SDK. Trong Python: ApiCreds được trả về từ client.create_api_key() sau khi bạn xác thực bằng wallet của mình. Trong Node.js: tương tự qua @polymarket/clob-client-v2 client.createApiKey(). Lưu key/secret/passphrase trả về vào .env của bạn (không bao giờ commit lên git).
Polymarket API keys có thể revoke không?
Có. Bạn có thể tạo key mới bất cứ lúc nào qua SDK; các key cũ vẫn hợp lệ cho đến khi bị revoke rõ ràng qua client.deleteApiKey(creds). Best practice là rotate keys định kỳ và revoke bất kỳ key nào đã chạm vào máy bị xâm phạm.
Điều gì thay đổi khi Polymarket migrate từ Magic Labs sang Privy?
OTP code đăng nhập từ 3 chữ số (dễ bị brute force, đã bị khai thác trong vụ hack tháng 12 năm 2025) chuyển sang code dài hơn cùng với device binding qua Privy. Với bot, thay đổi thực tế là quy trình auth - SDK che giấu phần lớn điều đó. Nếu bot của bạn hard-code các endpoint Magic Labs API (hiếm), hãy cập nhật sang luồng Privy.
Tôi có nên lưu key trong file .env không?
Với bot chạy trên một VPS duy nhất - có, với quyền file phù hợp (chmod 600 .env, thuộc về user chạy bot). Với thiết lập nhiều máy hoặc vận hành cấp production - hãy chuyển sang secrets manager (AWS Secrets Manager, Vault, doppler.com). Tuyệt đối không commit .env lên git, không bao giờ.