Autenticação na API CLOB v2: Chaves e Permissões

Aula 12: Autenticação na API CLOB v2

Para operar programaticamente na Polymarket, precisas de autenticação L1 (assinatura com a wallet) para derivar as tuas credenciais de API. O fluxo é feito uma vez; depois usas key + secret + passphrase para todas as chamadas.

Mecanismo: A API CLOB v2 usa um esquema de autenticação em duas camadas. A camada L1 deriva as credenciais a partir da tua chave privada sem a expor. A camada L2 usa essas credenciais para autenticar chamadas REST e WebSocket.

import { ClobClient, Chain } from "@polymarket/clob-client-v2";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import "dotenv/config";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const walletClient = createWalletClient({
  account,
  transport: http("https://polygon-rpc.com"),
});

const client = new ClobClient({
  host: "https://clob.polymarket.com",
  chain: Chain.POLYGON,
  signer: walletClient,
});

// L1 Authentication — wallet signature
const creds = await client.createOrDeriveApiKey();
console.log("Key:", creds.key);
console.log("Secret:", creds.secret);
console.log("Passphrase:", creds.passphrase);

Aprofundamento operacional

Autenticacao nao e apenas conseguir uma resposta 200 da API. E construir um limite claro entre permissao de leitura, permissao de trading e permissao de custodia. Quanto mais poderoso e o segredo, menor deve ser sua exposicao no sistema.

Use o principio do menor privilegio: scripts de leitura nao precisam de credenciais de execucao; bots em teste nao precisam de capital relevante; credenciais de producao nao devem estar em notebooks, prints, repositorios ou logs. A seguranca aqui e parte da performance, porque um vazamento pode destruir anos de processo em minutos.

Estrutura recomendada

• Um arquivo local ignorado pelo Git para segredos.
• Variaveis de ambiente separadas por ambiente: leitura, teste e producao.
• Rotacao periodica de credenciais.
• Logs sem private key, secret, passphrase ou headers assinados.
• Kill switch para qualquer script que possa enviar ordens.

Exercicio pratico

Crie uma checklist de seguranca do seu ambiente antes de rodar qualquer script autenticado. Inclua: Git status, .gitignore, variaveis carregadas, modo dry-run, limite de stake e destino dos logs.

Auditoria aplicada

Esta aula deve terminar com uma pequena auditoria escrita. O objetivo nao e produzir uma nota bonita, mas transformar “Autenticação na API CLOB v2: Chaves e Permissões” em uma decisao verificavel. Use os conceitos centrais da aula (os conceitos principais da aula) para construir um registro que possa ser revisado depois, quando o mercado ja tiver se movido ou o evento ja tiver sido resolvido.

Comece pela pergunta operacional: o que eu consigo observar agora que muda minha decisao? Depois separe evidencia, inferencia e decisao. Evidencia e dado verificavel: preco, spread, profundidade, regra de resolucao, horario, volume, estado do book, endpoint consultado ou custo calculado. Inferencia e a leitura que voce faz a partir desses dados. Decisao e o que voce faz com a leitura: estudar mais, descartar, entrar com ordem limit, esperar liquidez, reduzir stake, usar API apenas para leitura ou classificar como No Bet.

Protocolo de revisao

1. Escreva a tese em uma frase curta.
2. Liste os tres dados que sustentam a tese.
3. Liste o principal dado que poderia invalidar a tese.
4. Defina o custo de estar errado: perda financeira, slippage, fee, tempo preso, erro de resolucao ou risco operacional.
5. Defina o gatilho de pausa. Se esse gatilho acontecer, a decisao deve ser reavaliada antes de qualquer nova ordem.

Perguntas de controle

• O mercado esta suficientemente liquido para o tamanho que eu quero usar?
• O preco atual ainda paga o risco depois de spread, fees e slippage?
• A regra de resolucao esta clara o suficiente para eu aceitar exposicao?
• Se eu estivesse explicando este trade para outra pessoa, conseguiria separar dado de opiniao?
• Existe um caminho simples de saida se a leitura estiver errada?

Saida esperada

No fim da aula, salve uma nota de cinco linhas: mercado observado, preco observado, risco principal, decisao tomada e motivo para revisar depois. Esse habito cria memoria operacional. Sem memoria, o operador repete erros com mais confianca. Com memoria, cada aula vira uma parte do sistema de pesquisa.