Polymarket Bot Tutorial · Sura ya 6 kati ya 32

Authentication na wallet setup ya Polymarket bot: proxy wallets vs EOA, API key generation kupitia SDK, sigType 2 kwa Gnosis Safe, best practices za key storage, na Magic-to-Privy migration.

Na Harley Young, mwandishi mkuu wa Polymarkets.co.il. Marekebisho ya mwisho: Mei 2026.

Sura hii inafunika nini

Mfumo wa wallet wa Polymarket una sehemu tatu zinazohama: externally owned account (EOA) inayosaini orders, smart-contract proxy inayoshikilia funds, na Polymarket CLOB API key inayoauthentikate HTTP requests. Kupata zote tatu zimewekwa wire kwa usahihi ni Day 1 failure ya kawaida zaidi kwa builders wapya, na ikawa zaidi ya kuchanganya baada ya August 2025 Magic Labs hadi Privy migration. Sura hii inapitia kila kipande katika setup order, na environment variables maalum na signature-type flag ambazo production code inahitaji.

  • Proxy wallet vs EOA: ya kufanya bot na
  • Kutengeneza API key (SDK steps)
  • sigType 2 na POLY_FUNDER_ADDRESS (Gnosis Safe)
  • Key storage: .env, vault, KMS
  • Magic Labs hadi Privy migration
  • Kuapproved USDC/pUSD spending
  • Wallet recovery na backup

Proxy wallet vs EOA: ya kufanya bot na

Polymarket inatumia smart-contract proxy wallet pattern. EOA yako - anwani iliyofungwa na private key yako - inasaini transactions na orders. Gnosis Safe iliyodeployed kwenye deterministic address inashikilia pUSD halisi na outcome shares. Proxy address ni inayoonekana katika "wallet" panel ya Polymarket UI; EOA ni inayosaini.

Kwa bots, daima unasaini na EOA (PRIVATE_KEY katika env) na unarejea proxy address kama POLY_FUNDER_ADDRESS katika CLOB client config. Kutuma orders na EOA kama funder kunazalisha "insufficient balance" errors hata wakati proxy imefunded.

Huwezi kufanya bot na EOA peke yake - web flow ya Polymarket daima inaunda proxy kwenye signup. Hakiki addresses zote mbili na polymarket wallet show kutoka CLI, au soma proxy address kutoka Polymarket UI settings.

Kutengeneza API key (SDK steps)

CLOB API inahitaji credentials tatu: key, secret, passphrase. Hizi sio wallet private key yako - ni HMAC-style credential set iliyofungwa na wallet yako, inayotumika kwa HTTP request authentication tu.

Tengeneza zote mara moja na 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)

Hifadhi output katika JSON file na uipakie kwenye kila bot start; usitengeneze upya kwa session - API server inacache credential set, na kuirotate mara kwa mara kunaweza kutrip rate-limit logic. Credentials hazikomi kamwe automatically. Rotate tu ikiwa unashutumu leak.

sigType 2 na POLY_FUNDER_ADDRESS (Gnosis Safe)

Hoja ya signature_type inadhibiti jinsi CLOB inavyovalidate signatures za order yako. Values tatu zipo; mbili ni za kweli:

  • 0 / EOA: EOA ni signer na funder. Inatumika kwa setups za ajabu ambapo watumiaji wameimport private key moja kwa moja.
  • 1 / POLY_PROXY: legacy Magic Labs proxy contract. Accounts nyingi za kabla ya 2025.
  • 2 / POLY_GNOSIS_SAFE: standard ya sasa. Funds katika Gnosis Safe, EOA inasaini.

Tumia signature_type=2 kwa account yoyote iliyoundwa baada ya August 2025 (Privy migration) au account yoyote ambapo unaweza kuona Gnosis Safe address katika Polymarket UI. POLY_FUNDER_ADDRESS env var lazima iwe Safe address, sio EOA. Mismatched signature_type dhidi ya funder type silently inazalisha order rejections zinazoonekana kama "insufficient allowance" au "balance: 0" - error message ni ya kupotosha.

Key storage: .env, vault, KMS

Storage tiers tatu zinazokubalika kwa EOA private key.

  1. .env file (single-machine development). File inaishi kwenye VPS, bot inasoma kwenye start, key haitoki host. Inafaa kwa wallets <$1k. chmod 600 .env na hakikisha .gitignore ya repo yako inaiexclude.
  2. Self-hosted vault (HashiCorp Vault, age-encrypted file, au systemd-creds). Inaongeza unlock step kwenye bot start. Inastahili kwa wallets katika $1k-$10k range.
  3. Cloud KMS (AWS KMS, GCP KMS). Bot inaita KMS kudecrypt key katika memory; key haigusi disk kamwe. Inastahili operational complexity tu juu ya $10k au kwa multi-bot fleets.

Kile usichofanya kamwe: kucommit private key kwa git, kuipaste katika chat, kuihifadhi katika password manager inayosync kwa cloud services bila local-only mode. On-chain blast radius ya Polymarket EOA leak ni pUSD balance yako yote na outcome share inventory.

Magic Labs hadi Privy migration

Mnamo August 2025 Polymarket ilihamisha primary embedded-wallet provider yao kutoka Magic Labs hadi Privy. Bot-facing effect ni ndogo lakini maalum.

Accounts za pre-migration (zilizoundwa kupitia Magic) kawaida zinatumia signature_type=1 (POLY_PROXY). Accounts za post-migration zinatumia signature_type=2 (POLY_GNOSIS_SAFE). Baadhi ya watumiaji walihamisha account yao ya zamani; baadhi waliweka asilia. Hakuna njia ya kujua kutoka kwa public API ni type gani account yako inatumia - unacheck kwa kujaribu kusaini order na kuangalia rejection.

Migration pia ilibadilisha jinsi UI inavyoonyesha funder address. Polymarket UI flows za zamani zilionyesha proxy address katika dashboard; current flow inaizika katika account settings. CLI command polymarket wallet show ni njia safi zaidi kuhakiki values zote mbili, bila kujali wakati account ilipoundwa.

Kuapproved USDC/pUSD spending

Ili CLOB ihamishe pUSD yako kwenye order match, proxy lazima imeapproved Polymarket exchange contracts kama spenders. Polymarket UI inaweka approvals hizi wakati wa deposit ya kwanza. Kwa bots zinazofund proxy moja kwa moja, lazima uziweke kwa mkono.

Approvals tatu za kuweka, mara moja kwa wallet:

  1. pUSD (ERC-20) → exchange contract
  2. Conditional Tokens (ERC-1155) → exchange contract (kwa kuuza shares)
  3. Conditional Tokens (ERC-1155) → NegRisk exchange contract (kwa kuuza NegRisk shares)

Endesha polymarket approve kutoka CLI kwenye setup ya kwanza. Transaction inagharimu cents chache katika MATIC gas. Hakiki na polymarket approve check - zote tatu zinapaswa kurejesha "approved." Silent bug ya kawaida zaidi kwa builders wapya ni kukosa NegRisk approval, ambayo inashindwa tu wakati wa kuuza shares kutoka multi-outcome markets na inaonekana kama balance error.

Wallet recovery na backup

Wallet ya bot ina elements mbili zinazoweza kurejeshwa: EOA private key, na Polymarket account password (inayogate access kupitia web UI lakini sio kupitia SDK).

EOA private key ni kitu pekee kinachojali kwa bot. Kupoteza = kupoteza kila kitu katika proxy. Cold backup: andika kwenye karatasi, mhuri katika envelope, hifadhi offsite. Hot backup: encrypted USB stick. Usiipume kwa email kwako mwenyewe; usihifadhi unencrypted katika cloud storage.

Polymarket account password inaweza kurejeshwa kupitia Magic Labs / Privy email recovery maadamu bado unadhibiti email asilia ya signup. Haigate bot access - bot inatumia EOA private key moja kwa moja.

Ikiwa unashutumu key leak: mara moja withdraw pUSD na outcome tokens kwenda kwa wallet mpya, tengeneza EOA mpya, redeploy bot na key mpya. Leaked key haiwezi kufutwa; inaweza tu kudrained.

Maswali yanayoulizwa mara kwa mara

Je, ninahitaji wallet tofauti kwa bot yangu?
Imependekezwa sana ndio. Tumia EOA mpya au email-account-derived proxy wallet mpya inayoshikilia tu capital uliyoallocate kwa bot. Ikiwa bot key inaleak, fedha za bot tu zipo hatarini - main holdings zako zinakaa salama.
Ni nini sigType 2 katika Polymarket API?
sigType 2 inaonyesha Gnosis Safe (proxy wallet) signature, inayotumika unapoingia na email/Google na Polymarket inakuundia proxy. Kwa sigType 2, POLY_FUNDER_ADDRESS environment variable lazima iwe PROXY address (inayoonyeshwa katika Polymarket UI), sio underlying EOA. Hii ni bug ya kawaida ya configuration.
Je, ninawezaje kutengeneza Polymarket API key?
Tumia SDK. Katika Python: ApiCreds inarudishwa na client.create_api_key() mara umeauthentikate na wallet yako. Katika Node.js: sawa kupitia @polymarket/clob-client-v2 client.createApiKey(). Hifadhi key/secret/passphrase iliyorudishwa katika .env yako (usicommit kamwe kwa git).
Je, Polymarket API keys zinaweza kurevoked?
Ndio. Unaweza kuderive keys mpya wakati wowote kupitia SDK; keys za zamani zinabaki valid mpaka zirevokedwa moja kwa moja kupitia client.deleteApiKey(creds). Best practice ni kurotate keys kwa muda na kurevoke key yoyote iliyogusa machine iliyochukuliwa.
Ni nini ilibadilika wakati Polymarket ilihamisha kutoka Magic Labs hadi Privy?
Login OTP codes zilibadilika kutoka digits 3 (zinazoshambulika kwa brute force, zilizoexploitiwa katika hack ya Disemba 2025) hadi codes ndefu pamoja na device binding kupitia Privy. Kwa bots, mabadiliko ya kivitendo ni auth ceremony - SDK inaabstract mengi yake. Ikiwa bot yako ilikuwa hard-coded kwa Magic Labs API endpoints (nadra), update kwa Privy flow.
Je, nihifadhi keys katika .env file?
Kwa single-VPS bot - ndio, na file permissions sahihi (chmod 600 .env, inayomilikiwa na bot user). Kwa multi-machine setups au production-grade ops - hamia kwa secrets manager (AWS Secrets Manager, Vault, doppler.com). Usicommit kamwe .env kwa git, kamwe.