Um bot de API da Polymarket precisa de uma resposta clara a uma pergunta operacional difícil: o que deve fazer quando enviou uma ordem, mas nunca recebeu uma resposta utilizável? A ordem pode ter sido rejeitada, aceite, parcialmente executada ou concluída. Um tempo de espera local excedido não distingue essas possibilidades.
Conceber para essa incerteza altera a arquitetura. O bot precisa de registos duráveis antes da transmissão, autoridade delimitada sobre nova exposição e um processo de recuperação que investiga a intenção original. Também precisa de continuar a observar a conta quando parou de criar novas ordens. Suspender decisões e perder visibilidade são ações diferentes.
Este guia descreve uma conceção educativa para o contexto da Polymarket International. A Polymarket US tem interfaces separadas de conta e plataforma. Todos os limites, quantidades, preços e cenários de falha aqui são exemplos inventados. A conceção não estabelece que uma estratégia de negociação tem uma vantagem nem autoriza qualquer ação real numa conta.
Defina um bot delimitado de API da Polymarket
Um bot delimitado de API da Polymarket tem limites explícitos de permissão: que conta pode utilizar, que contratos pode considerar, que tipos de ordem pode criar e quanta exposição pode acrescentar. Esses limites devem ser impostos fora do componente de previsão, para que um sinal errado não possa simplesmente declarar-se isento.
Um bot inventado pode observar todos os mercados de uma lista de investigação, mas propor ordens apenas para dois contratos aprovados. Pode ter um limite de trinta unidades por evento e um compromisso máximo separado de compra. A amplitude de observação não implica autoridade equivalente para negociar.
O guia anterior de API de bots da Polymarket explica capacidades e modos de falha. Utilize essa distinção ao conceber o bot: acesso a dados, criação de ordens, cancelamento e operações da carteira são capacidades separadas. Uma funcionalidade só pertence ao programa quando o seu objetivo e limite de autorização são claros.
Separe a previsão do executor
O componente de previsão deve produzir uma proposta que contém um contrato, uma direção, a quantidade pretendida, o custo máximo e a expiração do raciocínio. Não deve deter diretamente autoridade irrestrita de assinatura. Um controlo separado de decisão pode verificar a proposta face ao estado atual da conta e aos limites operacionais.
Esta separação é útil mesmo quando uma pessoa opera todo o sistema. Torna o comportamento do programa inspecionável: a proposta explica por que uma negociação foi considerada, enquanto o controlo explica se era permitida. Uma proposta rejeitada continua a fazer parte do registo de investigação sem criar uma ordem.
O executor deve aceitar apenas uma instrução totalmente especificada e autorizada. Não deve improvisar uma quantidade maior ou um preço mais amplo porque a primeira tentativa não foi executada. Essas mudanças alteram a decisão económica e exigem nova validação face à conta e às provas atuais da estratégia.
Preserve uma intenção económica ao longo das tentativas
Uma intenção económica descreve a mudança pretendida na conta, enquanto uma tentativa de transporte descreve um esforço para comunicar uma instrução. Confundi-las é uma fonte comum de duplicação. Um tempo de espera excedido seguido de um pedido novo não deve tornar-se automaticamente um segundo desejo independente de comprar a mesma quantidade.
Atribua à intenção um identificador local estável e registe as condições aprovadas. Ligue cada pedido, resposta, identificador de ordem e observação de negociação a essa intenção quando a relação for conhecida. Se uma instrução posterior a substituir, registe explicitamente essa relação, em vez de substituir o histórico antigo.
O guia de negociação pela API da Kalshi fornece uma comparação de conciliação da conta noutro contexto de API. A distinção geral entre intenção e tentativa transfere-se, mas os mecanismos disponíveis para consulta e tratamento de duplicados diferem. Um bot tem de verificar a semântica efetiva da plataforma, em vez de pressupor uma funcionalidade universal de idempotência.
Escreva primeiro o diário durável de intenções
O diário durável de intenções tem de existir antes de uma ação poder chegar à plataforma. Caso contrário, uma falha depois da transmissão pode deixar uma ordem ativa sem explicação local. Guardar de forma persistente depois de receber uma resposta é demasiado tarde para esta janela específica de falha.
Registe conta, contrato, lado, quantidade, limite de preço, tempo de vida, versão da estratégia, resultado da autorização e reserva. Acrescente a identidade do pedido ou a referência à ordem assinada necessária para recuperação sem expor segredos em registos comuns. O diário deve suportar a leitura do histórico depois de o processo reiniciar.
Uma entrada no diário não é prova de que uma ordem foi enviada. Preserve etapas separadas para preparada, transmissão iniciada e resposta observada. Estas etapas ajudam a restringir a incerteza, embora não consigam eliminar toda a ambiguidade em torno de um limite de rede. O estado honesto de recuperação pode continuar a ser desconhecido até serem obtidas provas da conta.
Reserve capacidade de forma atómica
Duas propostas podem chegar em momentos próximos e ambas ver o mesmo orçamento aparentemente disponível. Se cada uma for aprovada independentemente antes de qualquer reserva ser registada, a exposição combinada pode exceder o limite. O controlo da conta precisa de uma operação consistente que verifica e reserva capacidade.
Suponha que um limite inventado de evento é de trinta unidades. A conta detém doze, e uma ordem ativa existente pode acrescentar oito. Apenas dez unidades adicionais cabem no limite. Se duas propostas novas pedirem dez cada e ambas lerem a mesma imagem antiga, aprovar ambas permitiria quarenta unidades no total.
Um registo partilhado de reservas impede essa corrida. A segunda proposta tem de ver a primeira reserva ou esperar até o seu resultado ser estabelecido. Processos de trabalho, estratégias ou interfaces de utilizador separados não criam capacidade económica separada quando utilizam a mesma conta e limite de evento.
Preserve reservas durante a incerteza
Uma submissão de resultado desconhecido pode ainda tornar-se exposição. Libertar a sua reserva apenas porque o pedido local excedeu o tempo de espera permite a outra proposta gastar a mesma capacidade. Conserve um compromisso conservador até a intenção original ser resolvida ou uma política documentada estabelecer uma alternativa segura.
No exemplo de trinta unidades, uma submissão incerta de dez unidades consome a capacidade restante para novas entradas. O bot pode continuar a ler dados de mercado, conciliar a conta e processar ações de redução de risco permitidas pela sua política. Não deve tratar a quantidade desconhecida como zero apenas para permanecer ativo.
Este comportamento deve estar visível para o operador. Um estado claro, como dez unidades reservadas à espera de conciliação da submissão, explica por que novas propostas estão suspensas. Sem essa explicação, um operador pode reiniciar o bot ou remover a reserva, derrotando involuntariamente o controlo que protegia a conta.
Utilize a configuração atual da conta e da carteira
O bot tem de verificar o signatário atual, a carteira da conta, as permissões e as autorizações de negociação antes de poder executar. Exemplos antigos podem pressupor um mecanismo diferente de carteira ou interface de cliente. Acesso bem-sucedido a dados públicos não valida o percurso privado de negociação.
A documentação de carteiras e autenticação da Polymarket é a referência atual para configuração específica da conta. Mantenha material secreto no ambiente autorizado de assinatura, separado de registos comuns da aplicação e de investigação. A recuperação deve depender de identificadores e provas da conta, não de expor credenciais para diagnosticar um pedido falhado.
Guarde a versão do cliente e a configuração juntamente com os registos operacionais. Se uma atualização alterar a construção de pedidos ou a interpretação das respostas, o bot deve passar os casos relevantes de recuperação antes de retomar autoridade. A compatibilidade é um comportamento a verificar, não uma propriedade implícita num nome familiar de pacote.
Diagnostique o ponto de falha
Um processo falhado pode parar antes da autorização, antes da transmissão, depois da transmissão ou durante a conciliação. Estes pontos têm implicações diferentes. Uma proposta rejeitada localmente não cria ordem. Um pedido cuja transmissão nunca começou pode ser repetido em segurança sob a mesma intenção. Um pedido com resultado remoto desconhecido precisa de investigação.
Registe informação suficiente de momento e estado para distinguir estes casos sem fingir saber mais do que as provas sustentam. O registo operacional pode dizer que o cliente começou a enviar num determinado momento e depois perdeu a ligação. Não pode concluir que a plataforma nunca recebeu os bytes apenas a partir desse erro local.
Utilize categorias de erro que levem a ações específicas. Falha de autenticação motiva revisão das credenciais ou conta. Incrementos inválidos de preço motivam revisão das restrições do mercado. Submissão de resultado desconhecido motiva conciliação da conta. Um mecanismo genérico de repetir tudo ignora a diferença entre corrigir um pedido e duplicar acidentalmente um válido.
Investigue através de provas de ordens e negociações
A recuperação de uma submissão de resultado desconhecido deve procurar provas associadas à intenção original utilizando os identificadores e interfaces suportados pela plataforma. Ordens abertas atuais, registos individuais de ordens e negociações da conta podem responder a partes diferentes da pergunta. Um elemento em falta numa lista nem sempre basta como prova de que não ocorreu execução.
O guia de gestão de ordens da Polymarket descreve leituras autenticadas para acompanhar ordens e negociações da conta. O bot deve combinar as provas relevantes com o seu diário durável. Deve também preservar a hora da consulta e qualquer limitação de cobertura, como paginação incompleta ou um fluxo desligado.
Depois de o estado ser estabelecido, atualize em conjunto a reserva e o registo da posição. Uma ordem ativa conserva o seu compromisso apropriado. Uma rejeição confirmada pode libertá-lo. Uma execução altera posições e custos. Se as provas continuarem contraditórias, mantenha explícita a incerteza e encaminhe o caso para o operador responsável.
Recomende e ganhe USDC
Recomende e ganhe USDCO nosso programa de afiliados paga em tempo real.
Não infira rejeição de uma lista vazia de ordens abertas
Uma ordem totalmente executada pode já não aparecer entre ordens abertas. Uma ordem imediata cuja quantidade não executada foi cancelada também pode não deixar uma entrada em espera. Olhar apenas para a lista de ordens abertas pode, por isso, classificar incorretamente uma execução completa ou parcial como um pedido que nunca existiu.
O bot tem de inspecionar os outros registos relevantes antes de decidir que a intenção original não teve efeito. Isto é especialmente importante quando um pedido podia ser executado imediatamente na submissão. O desaparecimento de um remanescente ativo não implica ausência de unidades adquiridas.
Uma perspetiva útil para o operador separa três perguntas: se uma ordem continua ativa, se ocorreram negociações e se as mudanças resultantes da conta estão conciliadas. Manter essas perguntas distintas impede que um painel visualmente vazio de ordens seja tratado como prova de que a conta não tem posições.
Concilie corretamente execuções parciais imediatas
O tipo de ordem determina o destino da quantidade não executada. A documentação atual da Polymarket define FAK como executar a quantidade disponível e cancelar o remanescente. Uma execução parcial FAK deixa uma posição, mas não deixa as unidades pedidas restantes em espera no livro.
Num caso inventado, um pedido FAK de dez unidades resulta em quatro unidades executadas a 0,43 $ e seis canceladas. O preço de compra é de 1,72 $ antes de comissões. Depois de serem estabelecidos a execução e o estado do remanescente, o bot deve registar quatro unidades e libertar a reserva associada às outras seis, sujeito às provas efetivas da conta.
Uma ordem em espera de dez unidades com quatro executadas e seis ativas é diferente. Conserva possível exposição futura. O modelo de estado do bot não deve utilizar um estado genérico de parcial como substituto tanto da quantidade executada como do estado final ou contínuo do remanescente.
Trate a corrida de cancelamento
Um pedido de cancelamento pode sobrepor-se a uma execução. O bot deve esperar conciliar ambos, em vez de pressupor que a sua intenção de cancelar removeu imediatamente a exposição. Um cancelamento bem-sucedido pode aplicar-se à quantidade restante depois de já ter ocorrido execução adicional.
Suponha que seis unidades parecem ativas quando o cancelamento começa e outras duas são executadas antes de o resto ser removido. O bot tem de acrescentar essas duas à posição e libertar apenas o compromisso que efetivamente terminou. Uma proposta de substituição deve utilizar o estado resultante da conta, não a quantidade visível antes da corrida.
O guia anterior de bots de negociação automática na Polymarket discute comportamento de pausa e reinício. O cancelamento é um componente desse processo, não uma reposição universal. Parar novas decisões, retirar ordens canceláveis e conciliar posições existentes são responsabilidades separadas que podem terminar em momentos diferentes.
Utilize um único percurso com autoridade para submeter
Vários processos de trabalho podem ajudar a recolher dados ou avaliar hipóteses independentes, mas a submissão de ordens precisa de autoridade coordenada. Se dois executores puderem agir sobre a mesma intenção sem um mecanismo partilhado de atribuição, ambos podem transmiti-la depois de um reinício ou mensagem atrasada.
Escolha uma regra clara de responsabilidade pelo executor ativo e torne visíveis as mudanças dessa responsabilidade. Um novo processo de trabalho não deve pressupor que um mais antigo parou apenas porque um sinal de atividade está atrasado. Precisa de um mecanismo que impeça ambos de utilizar simultaneamente a mesma autoridade ou de uma política que suspenda até a responsabilidade ser estabelecida.
O objetivo não é acrescentar complexidade por si só. Um bot de um único processo pode utilizar uma conceção simples, desde que o comportamento de reinício seja explícito. À medida que o sistema cresce, preserve a mesma garantia económica: uma intenção aprovada não pode tornar-se várias ordens independentes porque vários componentes acreditam ser responsáveis por a concluir.
Reconstrua antes de retomar depois do reinício
Um reinício deve começar com observação e conciliação. Carregue intenções por resolver, inspecione ordens e negociações atuais, verifique a identidade da conta e compare posições recuperadas com o registo local. Nova exposição deve esperar até as discrepâncias relevantes serem resolvidas ou explicitamente tratadas segundo a política operacional.
Não reproduza cada entrada inacabada do diário como uma nova ordem. Algumas entradas inacabadas podem corresponder a execuções remotas cujas respostas se perderam. Outras podem nunca ter saído do processo. O percurso de recuperação tem de as classificar utilizando provas, em vez de tratar um indicador local de conclusão em falta como permissão para transmitir novamente.
O guia de bots de API da Kalshi descreve casos de aceitação para outra plataforma. Utilize essa comparação para tornar mais precisas as perguntas de recuperação mantendo separados identificadores e comportamento de pedidos específicos da plataforma. O mesmo cenário de falha pode exigir consultas diferentes em interfaces diferentes.
Mantenha a observação ativa enquanto as decisões estão suspensas
Um bot que suspende novas entradas deve normalmente continuar as operações de leitura necessárias para compreender a sua conta. Desativar todos os componentes pode tornar um estado incerto mais difícil de resolver e deixar o operador sem informação atual sobre ordens ou posições ativas.
Defina modos operacionais em termos de capacidades. Um modo apenas de observação pode atualizar dados de mercado e da conta. Um modo de conciliação pode investigar ações anteriores. Um modo de cancelamento pode permitir operações específicas de redução de risco se autorizadas. Um modo de negociação pode criar nova exposição dentro dos seus limites.
Cada modo deve ter condições claras de entrada e saída. Uma recuperação de rede, por si só, não deve restaurar automaticamente a negociação se continuarem intenções por resolver. Inversamente, uma interrupção da fonte de investigação não tem de impedir conciliação da conta através de uma interface privada saudável. Limites detalhados de capacidades ajudam o bot a continuar útil sem exceder a sua autoridade.
Torne acionáveis as mensagens ao operador
Um operador deve receber uma explicação concisa do estado por resolver: a conta, o contrato, a intenção original, a exposição possível, as últimas provas verificadas e o passo seguinte de investigação. Um rasto de erro de programação, por si só, não explica a consequência económica da falha.
Evite pedir ao operador que escolha entre repetir e ignorar sem contexto. As ações disponíveis podem incluir consultar a ordem original, verificar negociações da conta, manter a suspensão ou escalar um registo contraditório. O bot deve preservar no diário o efeito de cada ação.
Uma revisão da plataforma pode ajudar a organizar essa interface. O guia de plataformas de negociação na Polymarket separa controlo da conta, formação do preço e liquidação. Essas distinções devem continuar visíveis durante falhas, quando um leitor tem especial probabilidade de confundir um ecrã funcional de dados de mercado com uma conta de negociação totalmente conciliada.
Teste falhas no limite da rede
Um exercício útil de aceitação interrompe o processo em vários pontos: depois da persistência da intenção, durante a transmissão, depois da aceitação remota mas antes do armazenamento local da resposta e depois de chegar uma execução mas antes de a perspetiva da posição ser atualizada. Cada interrupção deve conduzir a um estado recuperável ou explicitamente por resolver.
O resultado esperado nem sempre é continuação automática. Alguns casos devem terminar numa suspensão porque as provas disponíveis não conseguem estabelecer com segurança o estado da conta. O teste deve verificar que o bot preserva reservas, evita exposição duplicada e dá ao operador informação suficiente para investigar.
Inclua mensagens duplicadas e atrasadas na reprodução. Reprocessar uma negociação já conhecida não deve acrescentar a sua quantidade duas vezes. Uma rejeição tardia deve ser associada ao pedido correto, em vez de substituir uma intenção diferente bem-sucedida. Estes casos testam o modelo de registos de forma mais significativa do que submeter repetidamente ordens normais sob condições ideais.
Reveja o registo económico do bot
As medidas operacionais devem incluir idade das intenções por resolver, atraso da conciliação, observações duplicadas e discrepâncias de reservas. A taxa de sucesso dos pedidos, por si só, pode parecer saudável enquanto o registo da conta está errado. Um pequeno número de submissões incertas pode importar mais do que milhares de leituras públicas bem-sucedidas.
O guia anterior de API de bots de mercados de previsão fornece uma perspetiva mais ampla de arquitetura. Reveja o bot nos seus limites: que provas entraram, que autoridade foi concedida, que instrução saiu e que estado da conta regressou. Estes limites identificam onde uma falha alterou significado ou excedeu o âmbito.
Mantenha separada a avaliação da estratégia. Um bot pode executar fielmente uma estratégia fraca, e uma previsão promissora pode ser comprometida por execução pouco fiável. O diário económico permite examinar ambas as perguntas sem atribuir cada resultado ao componente mais visível ou à mensagem de erro mais recente.
Mantenha o bot de API da Polymarket dentro das suas provas
Um bot bem delimitado sabe quando tem provas suficientes para agir e quando só tem provas suficientes para investigar. O seu diário durável liga uma intenção às suas tentativas, ordens e negociações. As suas reservas têm em conta exposição possível até a incerteza ser resolvida.
Comece com um conjunto restrito de permissões e uma história completa de recuperação. Verifique a configuração da conta face à documentação atual, coordene autoridade de submissão e teste interrupções antes de alargar o âmbito. Torne explicáveis as suspensões e mantenha disponível a observação necessária para as resolver.
O resultado é um programa cujo comportamento pode ser reconstruído no funcionamento normal e em falha. Não transforma previsões incertas em resultados certos. Torna, sim, precisa a alegação operacional: o bot deve realizar apenas as ações delimitadas que foi autorizado a tentar e depois estabelecer o que efetivamente aconteceu antes de tratar a conta como pronta para outra decisão.