Polymarket Bot Tutorial · Chapter 6 of 32

Аутентифікація Polymarket bot і налаштування wallet: proxy wallets vs EOA, генерація API key через SDK, sigType 2 для Gnosis Safe, best practices для зберігання key і міграція з Magic на Privy.

Авторка: Гарлі Янг, провідна письменниця Polymarkets.co.il. Останній перегляд: травень 2026.

Що охоплює ця chapter

Wallet model Polymarket має три складові: externally owned account (EOA), який підписує orders, smart-contract proxy, що зберігає funds, і Polymarket CLOB API key, який аутентифікує HTTP requests. Коректно зв’язати всі три - це найпоширеніша Day 1 помилка для нових builders, і після міграції Magic Labs до Privy в серпні 2025 року це стало ще заплутанішим. У цій chapter ми розберемо кожен елемент у порядку налаштування, разом із конкретними environment variables і signature-type flag, які потрібні production code.

  • Proxy wallet vs EOA: з чим botити
  • Generating an API key (SDK steps)
  • sigType 2 and POLY_FUNDER_ADDRESS (Gnosis Safe)
  • Key storage: .env, vault, KMS
  • The Magic Labs to Privy migration
  • Approving USDC/pUSD spending
  • Wallet recovery and backup

Proxy wallet vs EOA: з чим botити

Polymarket використовує pattern smart-contract proxy wallet. Ваш EOA - адреса, прив’язана до вашого private key, - підписує transactions і orders. Gnosis Safe, розгорнутий за детермінованою адресою, зберігає фактичні pUSD і outcome shares. Proxy address - це те, що відображається в панелі "wallet" у UI Polymarket; EOA - це те, що підписує.

Для bot завжди підписуйте через EOA (PRIVATE_KEY в env) і вказуйте proxy address як POLY_FUNDER_ADDRESS у config CLOB client. Надсилання orders із EOA як funder спричиняє помилки "insufficient balance" навіть тоді, коли proxy поповнений.

Botити лише з EOA не можна - web flow Polymarket завжди створює proxy під час signup. Підтвердьте обидві адреси через polymarket wallet show з CLI або прочитайте proxy address у settings UI Polymarket.

Generating an API key (SDK steps)

CLOB API вимагає три credentials: key, secret, passphrase. Це не ваш wallet private key - це набір credentials у стилі HMAC, прив’язаний до вашого wallet, який використовується лише для HTTP request authentication.

Згенеруйте їх один раз за допомогою 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)

Збережіть output у JSON file і завантажуйте його під час кожного запуску bot; не регенеруйте його для кожної session - API server кешує набір credentials, і часта ротація може спровокувати rate-limit logic. Ці credentials не закінчуються автоматично. Ротуйте їх лише якщо підозрюєте leak.

sigType 2 and POLY_FUNDER_ADDRESS (Gnosis Safe)

Аргумент signature_type визначає, як CLOB валідуює ваші order signatures. Існує три значення; два з них реальні:

  • 0 / EOA: EOA є і signer, і funder. Використовується для незвичних setups, де користувачі імпортували private key напряму.
  • 1 / POLY_PROXY: legacy Magic Labs proxy contract. Більшість accounts до 2025 року.
  • 2 / POLY_GNOSIS_SAFE: поточний standard. Funds зберігаються в Gnosis Safe, EOA підписує.

Використовуйте signature_type=2 для будь-якого account, створеного після серпня 2025 року (міграція Privy) або для будь-якого account, де в UI Polymarket видно адресу Gnosis Safe. Env var POLY_FUNDER_ADDRESS має містити адресу Safe, а не EOA. Невідповідність signature_type типу funder тихо спричиняє відхилення orders, які виглядають як "insufficient allowance" або "balance: 0" - повідомлення про помилку вводить в оману.

Key storage: .env, vault, KMS

Три розумні рівні зберігання для EOA private key.

  1. .env file (single-machine development). File знаходиться на VPS, bot читає його під час запуску, key ніколи не залишає host. Достатньо для wallet менше ніж на <$1k. chmod 600 .env і переконайтеся, що .gitignore вашого repo виключає його.
  2. Self-hosted vault (HashiCorp Vault, age-encrypted file, або systemd-creds). Додає unlock step під час запуску bot. Варто використовувати для wallet у діапазоні $1k-$10k.
  3. Cloud KMS (AWS KMS, GCP KMS). Bot звертається до KMS, щоб розшифрувати key в memory; key ніколи не потрапляє на disk. Варто операційної складності лише понад $10k або для multi-bot fleets.

Чого ніколи не робити: не комітити private key у git, не вставляти його в chat, не зберігати його в password manager, який синхронізується з cloud services без local-only mode. On-chain blast radius витоку Polymarket EOA - це весь ваш pUSD balance і inventory outcome shares.

The Magic Labs to Privy migration

У серпні 2025 року Polymarket мігрував свого основного embedded-wallet provider з Magic Labs на Privy. Для bot вплив невеликий, але конкретний.

Облікові записи до міграції (створені через Magic) зазвичай використовують signature_type=1 (POLY_PROXY). Облікові записи після міграції використовують signature_type=2 (POLY_GNOSIS_SAFE). Деякі користувачі мігрували старий account; інші залишили початковий. Немає способу дізнатися з public API, який тип використовує ваш account - це перевіряють, намагаючись підписати order і спостерігаючи rejection.

Міграція також змінила спосіб, у який UI показує funder address. Старі flow UI Polymarket показували proxy address у dashboard; поточний flow ховає його в account settings. Команда CLI polymarket wallet show - найчистіший спосіб підтвердити обидва значення, незалежно від того, коли було створено account.

Approving USDC/pUSD spending

Щоб CLOB міг переміщувати ваш pUSD під час match order, proxy має надати approval exchange contracts Polymarket як spenders. UI Polymarket встановлює ці approvals під час першого deposit. Для bot, які поповнюють proxy напряму, їх потрібно встановити вручну.

Три approval, які треба встановити один раз на wallet:

  1. pUSD (ERC-20) → exchange contract
  2. Conditional Tokens (ERC-1155) → exchange contract (для selling shares)
  3. Conditional Tokens (ERC-1155) → NegRisk exchange contract (для selling NegRisk shares)

Запустіть polymarket approve з CLI під час першого setup. Transaction коштує кілька центів у MATIC gas. Перевірте через polymarket approve check - усі три мають повернути "approved." Найпоширеніший silent bug для нових builders - відсутній NegRisk approval, який проявляється лише під час selling shares із multi-outcome markets і виглядає як balance error.

Wallet recovery and backup

Wallet bot має два відновлювані елементи: EOA private key і password облікового запису Polymarket (який обмежує доступ через web UI, але не через SDK).

EOA private key - це єдине, що має значення для bot. Втрата = втрата всього, що є в proxy. Cold backup: запишіть його на папері, запечатайте в конверт, зберігайте поза офісом. Hot backup: зашифрована USB-флешка. Ніколи не надсилайте його собі email; ніколи не зберігайте незашифрованим у cloud storage.

Password облікового запису Polymarket можна відновити через Magic Labs / Privy email recovery, якщо ви досі контролюєте original signup email. Він не обмежує доступ ботові - bot використовує EOA private key напряму.

Якщо ви підозрюєте leak key: негайно виведіть pUSD і outcome tokens на новий wallet, згенеруйте новий EOA, розгорніть bot заново з новим key. Витіклий key не можна відкликати; його можна лише вичерпати.

Часті запитання

Чи потрібен окремий wallet для мого bot?
Так, це дуже рекомендовано. Використовуйте свіжий EOA або свіжий proxy wallet, створений із email-account, який зберігає лише capital, виділений для bot. Якщо key bot витече, під ризиком будуть лише funds bot - ваші основні holdings залишаться в безпеці.
Що таке sigType 2 в Polymarket API?
sigType 2 означає signature від Gnosis Safe (proxy wallet), який використовується, коли ви входите через email/Google, а Polymarket створює proxy для вас. Для sigType 2 env var POLY_FUNDER_ADDRESS має бути адресою PROXY (тією, що показана в UI Polymarket), а не underlying EOA. Це поширений bug конфігурації.
Як згенерувати Polymarket API key?
Використовуйте SDK. У Python: ApiCreds, що повертається client.create_api_key() після того, як ви автентифікувалися своїм wallet. У Node.js: аналогічно через @polymarket/clob-client-v2 client.createApiKey(). Збережіть отримані key/secret/passphrase у свій .env (ніколи не комітьте в git).
Чи можна відкликати Polymarket API keys?
Так. Ви можете згенерувати нові keys у будь-який момент через SDK; старі keys залишаються дійсними, доки їх явно не відкличете через client.deleteApiKey(creds). Best practice - періодично ротувати keys і відкликати будь-який key, який використовувався на скомпрометованій machine.
Що змінилося, коли Polymarket мігрував із Magic Labs на Privy?
OTP-коди для login стали не 3-значними (що було вразливим до brute force і було exploited у зламі грудня 2025), а довшими, плюс додалося device binding через Privy. Для bot практична зміна - це auth ceremony; SDK абстрагує більшу її частину. Якщо ваш bot був жорстко прив’язаний до Magic Labs API endpoints (це рідкість), оновіть його до Privy flow.
Чи варто зберігати keys у .env file?
Для bot на одному VPS - так, із правильними file permissions (chmod 600 .env, власник - користувач bot). Для multi-machine setups або production-grade ops - перейдіть на secrets manager (AWS Secrets Manager, Vault, doppler.com). Ніколи, за жодних обставин, не комітьте .env у git.