Polymarket Bot Tutorial · Chapter 6 of 32

Polymarket bot authentication and wallet setup: proxy wallets vs EOA, API key generation via SDK, sigType 2 for Gnosis Safe, key storage best practices, and the Magic-to-Privy migration.

تحریر: ہارلی ینگ، Polymarkets.co.il کی مرکزی مصنفہ۔ آخری جائزہ: مئی 2026۔

اس chapter میں کیا شامل ہے

  • Proxy wallet vs EOA: کس کے ساتھ bot کرنا ہے
  • API key generate کرنا (SDK steps)
  • sigType 2 اور POLY_FUNDER_ADDRESS (Gnosis Safe)
  • Key storage: .env, vault, KMS
  • Magic Labs سے Privy migration
  • USDC/pUSD spending approve کرنا
  • Wallet recovery اور backup

Proxy wallet vs EOA: کس کے ساتھ bot کرنا ہے

Polymarket ایک smart-contract proxy wallet pattern استعمال کرتا ہے۔ آپ کا EOA - یعنی وہ address جو آپ کے private key سے linked ہے - transactions اور orders sign کرتا ہے۔ ایک Gnosis Safe جو deterministic address پر deployed ہوتا ہے، اصل pUSD اور outcome shares رکھتا ہے۔ Proxy address وہی ہے جو Polymarket UI کے "wallet" panel میں دکھائی دیتا ہے؛ EOA وہ ہے جو sign کرتی ہے۔

Bots کے لیے، آپ ہمیشہ EOA کے ساتھ sign کرتے ہیں (PRIVATE_KEY env میں) اور CLOB client config میں proxy address کو POLY_FUNDER_ADDRESS کے طور پر refer کرتے ہیں۔ اگر funder کے طور پر EOA سے order بھیجا جائے تو proxy funded ہونے کے باوجود "insufficient balance" errors آتی ہیں۔

آپ صرف EOA کے ساتھ bot نہیں چلا سکتے - Polymarket کا web flow signup پر ہمیشہ ایک proxy create کرتا ہے۔ دونوں addresses کو polymarket wallet show سے CLI میں confirm کریں، یا Polymarket UI کی settings سے proxy address پڑھیں۔

API key generate کرنا (SDK steps)

CLOB API کو تین credentials درکار ہوتے ہیں: key, secret, passphrase۔ یہ آپ کا wallet private key نہیں ہیں - یہ HMAC-style credential set ہے جو آپ کے wallet سے bound ہوتا ہے، اور صرف HTTP request authentication کے لیے استعمال ہوتا ہے۔

SDK کے ساتھ انہیں ایک بار generate کریں:

# 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 میں store کریں اور bot start ہونے پر ہر بار load کریں؛ ہر session میں دوبارہ generate نہ کریں - API server credential set کو cache کرتا ہے، اور بار بار rotate کرنے سے rate-limit logic trigger ہو سکتا ہے۔ Credentials خود بخود expire نہیں ہوتے۔ صرف اسی صورت rotate کریں جب leak کا شک ہو۔

sigType 2 اور POLY_FUNDER_ADDRESS (Gnosis Safe)

signature_type argument یہ control کرتا ہے کہ CLOB آپ کے order signatures کو کیسے validate کرے۔ تین values موجود ہیں؛ دو حقیقی ہیں:

  • 0 / EOA: EOA signer بھی ہے اور funder بھی۔ یہ unusual setups میں استعمال ہوتا ہے جہاں users نے private key براہِ راست import کی ہو۔
  • 1 / POLY_PROXY: legacy Magic Labs proxy contract۔ زیادہ تر pre-2025 accounts۔
  • 2 / POLY_GNOSIS_SAFE: current standard۔ Funds Gnosis Safe میں ہوتے ہیں، EOA sign کرتی ہے۔

August 2025 (Privy migration) کے بعد بننے والے کسی بھی account، یا ایسے account کے لیے جس کے Polymarket UI میں Gnosis Safe address نظر آتا ہو، signature_type=2 استعمال کریں۔ POLY_FUNDER_ADDRESS env var Safe address ہونا چاہیے، EOA نہیں۔ Funder type کے ساتھ mismatched signature_type خاموشی سے ایسے order rejections پیدا کرتا ہے جو "insufficient allowance" یا "balance: 0" جیسے لگتے ہیں - error message misleading ہوتا ہے۔

Key storage: .env, vault, KMS

EOA private key ذخیرہ کرنے کے تین مناسب tiers ہیں۔

  1. .env file (single-machine development). File VPS پر رہتی ہے، bot start ہونے پر اسے read کرتا ہے، key host سے باہر نہیں جاتی۔ <$1k wallets کے لیے کافی ہے۔ chmod 600 .env کریں اور یقینی بنائیں کہ آپ کے repo کی .gitignore اسے exclude کرتی ہو۔
  2. Self-hosted vault (HashiCorp Vault, age-encrypted file, یا systemd-creds). Bot start پر unlock step شامل ہوتا ہے۔ $1k-$10k range کے wallets کے لیے worth it ہے۔
  3. Cloud KMS (AWS KMS, GCP KMS). Bot key کو memory میں decrypt کرنے کے لیے KMS call کرتا ہے؛ key کبھی disk کو touch نہیں کرتی۔ یہ operational complexity صرف $10k سے اوپر یا multi-bot fleets کے لیے worth ہے۔

جو چیزیں کبھی نہیں کرنی چاہئیں: private key کو git میں commit کرنا، اسے chat میں paste کرنا، یا اسے ایسے password manager میں store کرنا جو local-only mode کے بغیر cloud services کے ساتھ sync ہوتا ہو۔ Polymarket EOA leak کا on-chain blast radius آپ کی پوری pUSD balance اور outcome share inventory ہے۔

Magic Labs سے Privy migration

August 2025 میں Polymarket نے اپنے primary embedded-wallet provider کو Magic Labs سے Privy پر migrate کیا۔ Bot-facing اثر چھوٹا ہے مگر specific ہے۔

Pre-migration accounts (جو Magic کے ذریعے create ہوئے تھے) عموماً signature_type=1 (POLY_PROXY) استعمال کرتے ہیں۔ Post-migration accounts signature_type=2 (POLY_GNOSIS_SAFE) استعمال کرتے ہیں۔ کچھ users نے اپنا پرانا account migrate کیا؛ کچھ نے original برقرار رکھا۔ Public API سے یہ جاننے کا کوئی طریقہ نہیں کہ آپ کا account کون سا type استعمال کرتا ہے - آپ order sign کرنے کی کوشش کر کے اور rejection دیکھ کر check کرتے ہیں۔

Migration نے UI میں funder address دکھانے کا طریقہ بھی بدل دیا۔ Older Polymarket UI flows dashboard میں proxy address دکھاتے تھے؛ current flow اسے account settings میں چھپا دیتا ہے۔ Account کب بھی create ہوا ہو، دونوں values confirm کرنے کے لیے polymarket wallet show CLI command سب سے صاف طریقہ ہے۔

USDC/pUSD spending approve کرنا

CLOB کو order match کے وقت آپ کا pUSD move کرنے کے لیے proxy کو Polymarket exchange contracts کو spender کے طور پر approve کرنا ضروری ہے۔ Polymarket UI پہلی deposit کے دوران یہ approvals set کرتا ہے۔ جو bots proxy کو direct fund کرتے ہیں، انہیں یہ manually set کرنا ہوتا ہے۔

ہر wallet کے لیے ایک بار کرنے والی تین approvals:

  1. pUSD (ERC-20) → exchange contract
  2. Conditional Tokens (ERC-1155) → exchange contract (shares sell کرنے کے لیے)
  3. Conditional Tokens (ERC-1155) → NegRisk exchange contract (NegRisk shares sell کرنے کے لیے)

First setup پر CLI سے polymarket approve چلائیں۔ Transaction کی gas cost چند cents MATIC میں ہوتی ہے۔ polymarket approve check سے verify کریں - تینوں کو "approved" return کرنا چاہیے۔ نئے builders کے لیے سب سے عام silent bug missing NegRisk approval ہے، جو صرف multi-outcome markets میں shares sell کرتے وقت fail ہوتا ہے اور balance error جیسا لگتا ہے۔

Wallet recovery اور backup

Bot کے wallet کے دو recoverable elements ہوتے ہیں: EOA private key، اور Polymarket account password (جو web UI کے ذریعے access gate کرتا ہے، SDK کے ذریعے نہیں)۔

Bot کے لیے صرف EOA private key اہم ہے۔ Loss = proxy میں موجود سب کچھ lost۔ Cold backup: اسے کاغذ پر لکھیں، envelope میں seal کریں، offsite store کریں۔ Hot backup: encrypted USB stick۔ کبھی اسے خود کو email نہ کریں؛ کبھی cloud storage میں unencrypted store نہ کریں۔

Polymarket account password Magic Labs / Privy email recovery کے ذریعے recover ہو سکتا ہے، جب تک آپ original signup email پر control رکھتے ہیں۔ یہ bot access کو gate نہیں کرتا - bot براہِ راست EOA private key استعمال کرتا ہے۔

اگر key leak کا شک ہو: فوراً pUSD اور outcome tokens کو نئے wallet میں withdraw کریں، نیا EOA generate کریں، اور نئے key کے ساتھ bot دوبارہ deploy کریں۔ Leaked key revoke نہیں ہو سکتی؛ اسے صرف drain کیا جا سکتا ہے۔

اکثر پوچھے گئے سوالات

کیا مجھے اپنے bot کے لیے الگ wallet چاہیے؟
سختی سے ہاں، recommend کیا جاتا ہے۔ ایک fresh EOA یا fresh email-account-derived proxy wallet استعمال کریں جس میں صرف وہی capital ہو جو آپ نے bot کے لیے allocate کیا ہے۔ اگر bot key leak ہو جائے تو صرف bot funds خطرے میں ہوں گے - آپ کی main holdings محفوظ رہیں گی۔
Polymarkets API میں sigType 2 کیا ہے؟
sigType 2 ایک Gnosis Safe (proxy wallet) signature کو indicate کرتا ہے، جو تب استعمال ہوتا ہے جب آپ email/Google سے log in کرتے ہیں اور Polymarket آپ کے لیے proxy create کرتا ہے۔ sigType 2 کے لیے POLY_FUNDER_ADDRESS environment variable PROXY address ہونا چاہیے (وہی جو Polymarket UI میں دکھائی دیتا ہے)، underlying EOA نہیں۔ یہ ایک عام configuration bug ہے۔
میں Polymarket API key کیسے generate کروں؟
SDK استعمال کریں۔ Python میں: ApiCreds client.create_api_key() سے returned ہوتے ہیں جب آپ اپنے wallet کے ساتھ authenticate کر چکے ہوں۔ Node.js میں: @polymarket/clob-client-v2 کے ذریعے اسی طرح client.createApiKey()۔ Returned key/secret/passphrase کو اپنے .env میں save کریں (کبھی git میں commit نہ کریں)۔
کیا Polymarket API keys revoke کی جا سکتی ہیں؟
جی ہاں۔ آپ SDK کے ذریعے کسی بھی وقت نئے keys derive کر سکتے ہیں؛ پرانے keys تب تک valid رہتے ہیں جب تک انہیں client.deleteApiKey(creds) کے ذریعے explicitly revoke نہ کیا جائے۔ بہترین طریقہ یہ ہے کہ keys کو periodically rotate کریں اور کسی بھی compromised machine سے touch ہونے والی key revoke کر دیں۔
Polymarket کے Magic Labs سے Privy migrate کرنے پر کیا بدلا؟
Login OTP codes 3 digits سے longer codes میں بدل گئے (جو brute force کے لیے vulnerable تھے، اور December 2025 hack میں exploit ہوئے) اور ساتھ Privy کے ذریعے device binding بھی شامل ہوئی۔ Bots کے لیے practical change auth ceremony ہے - SDK زیادہ تر کام abstract کر دیتا ہے۔ اگر آپ کا bot hard-coded Magic Labs API endpoints پر تھا (جو کم ہوتا ہے)، تو اسے Privy flow پر update کریں۔
کیا مجھے keys .env file میں store کرنی چاہئیں؟
Single-VPS bot کے لیے - ہاں، proper file permissions کے ساتھ (chmod 600 .env، اور file bot user کی owned ہو)۔ Multi-machine setups یا production-grade ops کے لیے - secrets manager (AWS Secrets Manager، Vault، doppler.com) پر منتقل ہو جائیں۔ .env کو کبھی بھی git میں commit نہ کریں، بالکل بھی نہیں۔