Polymarket Bot Tutorial · Capítulo 6 de 32

Autenticação do bot Polymarket e configuração de wallet: proxy wallets vs EOA, geração de API key via SDK, sigType 2 para Gnosis Safe, melhores práticas de armazenamento de chaves e a migração do Magic para o Privy.

Por Harley Young, redatora líder em Polymarkets.co.il. Última revisão: maio de 2026.

O que este capítulo aborda

O modelo de wallet da Polymarket tem três partes em movimento: uma externally owned account (EOA) que assina ordens, um smart-contract proxy que mantém os fundos e a Polymarket CLOB API key que autentica requisições HTTP. Fazer essas três peças funcionarem corretamente é a falha mais comum no primeiro dia para novos builders, e isso ficou ainda mais confuso após a migração do Magic Labs para Privy em agosto de 2025. Este capítulo percorre cada parte na ordem de configuração, com as variáveis de ambiente específicas e o sinalizador de signature-type que o código de produção precisa.

  • Proxy wallet vs EOA: qual usar para botar
  • Gerando uma API key (etapas do SDK)
  • sigType 2 e POLY_FUNDER_ADDRESS (Gnosis Safe)
  • Armazenamento de chaves: .env, vault, KMS
  • A migração do Magic Labs para Privy
  • Aprovando gastos de USDC/pUSD
  • Recuperação e backup de wallet

Proxy wallet vs EOA: qual usar para botar

A Polymarket usa um padrão de proxy wallet em smart-contract. Sua EOA - o endereço vinculado à sua private key - assina transações e ordens. Um Gnosis Safe implantado em um endereço determinístico mantém o pUSD e as outcome shares de fato. O endereço proxy é o que aparece no painel "wallet" da UI da Polymarket; a EOA é o que assina.

Para bots, você sempre assina com a EOA (PRIVATE_KEY no env) e referencia o endereço proxy como POLY_FUNDER_ADDRESS na configuração do CLOB client. Enviar ordens usando a EOA como funder gera erros de "insufficient balance" mesmo quando o proxy está financiado.

Você não pode botar apenas com a EOA - o fluxo web da Polymarket sempre cria um proxy no cadastro. Confirme ambos os endereços com polymarket wallet show no CLI, ou leia o endereço proxy nas configurações da UI da Polymarket.

Gerando uma API key (etapas do SDK)

A CLOB API requer três credenciais: key, secret, passphrase. Essas não são a private key da sua wallet - são um conjunto de credenciais no estilo HMAC vinculado à sua wallet, usado apenas para autenticação de requisições HTTP.

Gere-as uma vez com o 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)

Armazene a saída em um arquivo JSON e carregue-a em cada inicialização do bot; não regenere por sessão - o API server armazena em cache o conjunto de credenciais, e rotacioná-las com frequência pode acionar a lógica de rate-limit. As credenciais nunca expiram automaticamente. Rotacione-as somente se suspeitar de vazamento.

sigType 2 e POLY_FUNDER_ADDRESS (Gnosis Safe)

O argumento signature_type controla como o CLOB valida as assinaturas das suas ordens. Existem três valores; dois são reais:

  • 0 / EOA: a EOA é tanto signer quanto funder. Usado em configurações incomuns em que usuários importaram uma private key diretamente.
  • 1 / POLY_PROXY: contrato proxy legado do Magic Labs. A maioria das contas pré-2025.
  • 2 / POLY_GNOSIS_SAFE: padrão atual. Fundos em um Gnosis Safe, EOA assina.

Use signature_type=2 para qualquer conta criada após agosto de 2025 (a migração para Privy) ou qualquer conta em que você possa ver um endereço Gnosis Safe na UI da Polymarket. A variável de ambiente POLY_FUNDER_ADDRESS deve ser o endereço do Safe, não a EOA. signature_type incompatível com o tipo de funder produz rejeições de ordem silenciosas que parecem "insufficient allowance" ou "balance: 0" - a mensagem de erro é enganosa.

Armazenamento de chaves: .env, vault, KMS

Três níveis razoáveis de armazenamento para a private key da EOA.

  1. Arquivo .env (desenvolvimento em uma única máquina). O arquivo fica na VPS, o bot o lê na inicialização, a chave nunca sai do host. Adequado para wallets de <$1k. chmod 600 .env e garanta que o .gitignore do seu repositório o exclua.
  2. Vault auto-hospedado (HashiCorp Vault, arquivo criptografado com age ou systemd-creds). Adiciona uma etapa de desbloqueio na inicialização do bot. Vale a pena para wallets na faixa de $1k-$10k.
  3. Cloud KMS (AWS KMS, GCP KMS). O bot chama o KMS para descriptografar a chave em memória; a chave nunca toca o disco. Vale a complexidade operacional apenas acima de $10k ou para frotas com vários bots.

O que nunca fazer: commitar uma private key no git, colá-la em um chat, armazená-la em um password manager que sincroniza com serviços de cloud sem modo local-only. O raio de explosão on-chain de um vazamento da EOA da Polymarket é todo o seu saldo de pUSD e o inventário de outcome shares.

A migração do Magic Labs para Privy

Em agosto de 2025, a Polymarket migrou seu principal provedor de embedded wallet de Magic Labs para Privy. O efeito voltado para bots é pequeno, mas específico.

Contas pré-migração (criadas via Magic) normalmente usam signature_type=1 (POLY_PROXY). Contas pós-migração usam signature_type=2 (POLY_GNOSIS_SAFE). Alguns usuários migraram sua conta antiga; outros mantiveram a original. Não há como saber pela API pública qual tipo sua conta usa - você verifica tentando assinar uma ordem e observando a rejeição.

A migração também mudou como a UI expõe o endereço do funder. Fluxos mais antigos da UI da Polymarket mostravam o endereço proxy no dashboard; o fluxo atual o esconde nas configurações da conta. O comando CLI polymarket wallet show é a forma mais limpa de confirmar ambos os valores, independentemente de quando a conta foi criada.

Aprovando gastos de USDC/pUSD

Para o CLOB mover seu pUSD no match da ordem, o proxy precisa ter aprovado os contratos de exchange da Polymarket como spenders. A UI da Polymarket define essas aprovações durante o primeiro depósito. Para bots que financiam o proxy diretamente, você precisa configurá-las manualmente.

Três aprovações para definir, uma vez por wallet:

  1. pUSD (ERC-20) → contract de exchange
  2. Conditional Tokens (ERC-1155) → contract de exchange (para vender shares)
  3. Conditional Tokens (ERC-1155) → contract de exchange NegRisk (para vender shares NegRisk)

Execute polymarket approve no CLI na primeira configuração. A transação custa alguns centavos em gas de MATIC. Verifique com polymarket approve check - os três devem retornar "approved." O bug silencioso mais comum para novos builders é a ausência da aprovação de NegRisk, que só falha ao vender shares de mercados com múltiplos resultados e parece um erro de saldo.

Recuperação e backup de wallet

A wallet do bot tem dois elementos recuperáveis: a private key da EOA e a senha da conta Polymarket (que controla o acesso pela UI web, mas não pelo SDK).

A private key da EOA é a única coisa que importa para o bot. Perda = perda de tudo no proxy. Backup frio: escreva em papel, lacre em um envelope, armazene fora do local. Backup quente: pendrive USB criptografado. Nunca envie por e-mail para si mesmo; nunca armazene sem criptografia em cloud storage.

A senha da conta Polymarket pode ser recuperada via recuperação por e-mail do Magic Labs / Privy, desde que você ainda controle o e-mail original de cadastro. Ela não controla o acesso do bot - o bot usa diretamente a private key da EOA.

Se suspeitar de vazamento de chave: imediatamente retire pUSD e tokens de resultado para uma nova wallet, gere uma nova EOA, reinstale o bot com a nova chave. A chave vazada não pode ser revogada; ela só pode ser esvaziada.

Perguntas frequentes

Preciso de uma wallet separada para meu bot?
Fortemente recomendado, sim. Use uma EOA nova ou uma proxy wallet nova derivada de uma conta de e-mail que mantenha apenas o capital alocado ao bot. Se a chave do bot vazar, apenas os fundos do bot ficam em risco - suas posições principais continuam seguras.
O que é sigType 2 na API da Polymarket?
sigType 2 indica uma assinatura de Gnosis Safe (proxy wallet), usada quando você entra com e-mail/Google e a Polymarket cria o proxy para você. Para sigType 2, a variável de ambiente POLY_FUNDER_ADDRESS deve ser o endereço do PROXY (o mostrado na UI da Polymarket), não a EOA subjacente. Esse é um bug de configuração comum.
Como gero uma Polymarket API key?
Use o SDK. Em Python: ApiCreds retornado por client.create_api_key() depois que você autenticar com sua wallet. Em Node.js: similar via @polymarket/clob-client-v2 client.createApiKey(). Salve a key/secret/passphrase retornada no seu .env (nunca commite no git).
As Polymarket API keys podem ser revogadas?
Sim. Você pode derivar novas keys a qualquer momento via SDK; as keys antigas continuam válidas até serem explicitamente revogadas via client.deleteApiKey(creds). A melhor prática é rotacionar as keys periodicamente e revogar qualquer key que tenha tocado uma máquina comprometida.
O que mudou quando a Polymarket migrou do Magic Labs para o Privy?
Os códigos OTP de login passaram de 3 dígitos (vulneráveis a brute force, explorados no hack de dezembro de 2025) para códigos mais longos mais device binding via Privy. Para bots, a mudança prática é o auth ceremony - o SDK abstrai a maior parte disso. Se seu bot estava com hard-code dos endpoints da API do Magic Labs (raro), atualize para o fluxo do Privy.
Devo armazenar chaves em um arquivo .env?
Para um bot em uma única VPS - sim, com permissões de arquivo adequadas (chmod 600 .env, pertencente ao usuário do bot). Para setups em várias máquinas ou operações em nível de produção - migre para um secrets manager (AWS Secrets Manager, Vault, doppler.com). Nunca, em hipótese alguma, commite o .env no git.