helebest/holo-polymarket

Consulta Polymarket

Um skill somente leitura para pesquisar mercados preditivos da Polymarket (nunca realiza ordens). Ele cobre duas necessidades:

• Pesquisa de mercado: eventos populares, busca, detalhes de eventos, preços históricos e tendências de probabilidade/volume.
• Rastreamento de posições e baleias: leaderboard, posições e P&L de qualquer endereço, e histórico de negociações.

Para realmente comprar/vender (enviar ordens, cancelar, saldos, gerenciamento de ordens), use o skill polymarket-trade.

Início rápido

1. Verifique o ambiente: bash, curl, jq e acesso a gamma-api.polymarket.com / data-api.polymarket.com / clob.polymarket.com.
2. Escolha um tipo de tarefa: informações de mercado / baleias e posições / tendências históricas.
3. Execute o comando correspondente: bash <diretorio-do-skill>/scripts/polymarket.sh <comando> [args...].

Lista completa de comandos: references/commands.md. Solução de problemas: references/troubleshooting.md.

Escolhendo um comando

• Mercados populares rapidamente: hot [limite].
• Encontrar mercados por palavra-chave: search <palavra-chave> [limite].
• Inspecionar um evento pelo slug (com tokens): detail <slug-do-evento>.
• Rastrear principais traders / verificar posições: leaderboard (alias lb) → positions (alias pos) → trades.
  • Apenas posições abertas: positions <endereco> [limite] --active.
  • Sua própria carteira: com POLYMARKET_FUNDER (ou FUNDER) definido, positions / trades usam esse valor por padrão quando nenhum endereço é fornecido. Use o endereço da sua carteira proxy (aquela que detém fundos/posições), não o signatário/EOA.
• Revisão de série temporal:
  • Tabela de probabilidade: history
  • Resumo de variação início/fim: trend
  • Variações de volume: volume-trend
• Exportação de arquivo: adicione --format csv|json e opcionalmente --out <arquivo> a history/trend/volume-trend.

Exemplos mínimos

# 1) Mercados populares
bash <diretorio-do-skill>/scripts/polymarket.sh hot 5

# 2) Busca + detalhe
bash <diretorio-do-skill>/scripts/polymarket.sh search bitcoin 5
bash <diretorio-do-skill>/scripts/polymarket.sh detail fed-decision-in-march-885

# 3) Rastreio de baleias e posições
bash <diretorio-do-skill>/scripts/polymarket.sh lb 10 pnl week
bash <diretorio-do-skill>/scripts/polymarket.sh pos 0xc257ea... 10
bash <diretorio-do-skill>/scripts/polymarket.sh pos 0xc257ea... 10 --active   # apenas abertas
bash <diretorio-do-skill>/scripts/polymarket.sh trades 0xc257ea... 10

# 4) Tendências históricas + exportação
bash <diretorio-do-skill>/scripts/polymarket.sh history fed-decision-in-march-885 2025-01-01 2025-01-31 1d
bash <diretorio-do-skill>/scripts/polymarket.sh trend fed-decision-in-march-885 2025-01-01 2025-01-31 --format csv
bash <diretorio-do-skill>/scripts/polymarket.sh volume-trend fed-decision-in-march-885 2025-01-01 2025-01-31 --format json --out /tmp/volume.json

Regras de parâmetros: from/to são YYYY-MM-DD; interval é 1h / 4h / 1d.

Falhas comuns

• Dependências ausentes: instale curl / jq.
• Falhas de rede: verifique a acessibilidade das APIs e timeout; aumente CURL_TIMEOUT se necessário. Em ambiente com proxy, HTTPS_PROXY é detectado automaticamente.
• Falhas no preço histórico: verifique POLYMARKET_BEARER_TOKEN ou um arquivo de credenciais (veja abaixo).
• Erros de argumento: verifique novamente o uso do comando e o formato da data (YYYY-MM-DD).

Credenciais (apenas o endpoint de preço histórico precisa)

O endpoint de preço histórico pode exigir um token bearer. Ele é resolvido nesta ordem (neutro ao agente, não vinculado a nenhum runtime):

1. Variável de ambiente POLYMARKET_BEARER_TOKEN
2. O arquivo nomeado por POLYMARKET_CREDENTIALS_FILE
3. ./.credentials no diretório do projeto (deve estar em .gitignore)
4. ~/.config/holo-polymarket/credentials
5. ~/.openclaw/credentials/polymarket_credentials (fallback legado)

O arquivo de credenciais é CHAVE=VALOR e suporta os campos BEARER_TOKEN / TOKEN.

O mesmo arquivo (ou env) pode também fornecer POLYMARKET_FUNDER / FUNDER — o endereço da sua carteira proxy. Quando definido, positions / trades usam esse valor por padrão se nenhum endereço for fornecido na linha de comando. Esta é a única identidade que o skill de consulta lê; todo o resto aqui é somente leitura e público.

Limite de negociação

Este skill é somente leitura e nunca envia ordens. Para comprar/vender, cancelar, saldos e gerenciamento de ordens, use o skill polymarket-trade (construído sobre a API CLOB oficial).