For the complete documentation index, see llms.txt. This page is also available as Markdown.

API

Seu próprio programa lê e opera nas exchanges que você conecta pela API do goodcryptoX, que o documento OpenAPI descreve. Um programa usa as mesmas chaves, permissões e limites de um agente de IA (Chaves e limites).

Cada valor vem na moeda da sua operação: preços e valores na moeda de cotação do mercado, um PnL no ativo que a sua linha indica, os créditos e GET /api/v1/portfolio em USD, os limites de uma chave na moeda em que foram definidos. GET /api/v1/rates responde a sua moeda base e a cotação dela por 1 USD, para mostrar um valor como o goodcryptoX mostra.

A ferramenta MCP instruments e GET /api/v1/instruments?venue=… incluem o volume conhecido de cada mercado em 24 horas (valor na moeda de cotação), a variação de preço (em porcentagem) e, quando a exchange o envia, o preço da última negociação. A API também fornece instrument-stats/<venue> pela sua rota de tópicos. Esses valores continuam sendo strings decimais. Para volume e variação, null mantém o valor conhecido anterior; o campo opcional invalidate indica quais valores apagar. Se lastPrice estiver ausente, o preço anterior é mantido por compatibilidade; um null explícito o apaga.

Em Configurações › MCP & API, crie uma chave (como); o lado API do bloco de conexão tem então três linhas, cada uma com um ícone de copiar: o Endereço, a Chave e o cabeçalho que seu programa envia a cada requisição, com a chave escolhida dentro: Authorization: Bearer <your key>. O ícone de copiar ao lado do cabeçalho o copia inteiro.

Exemplo de requisição à API

Defina GCX_URL com a origem que o seu programa alcança e forneça GCX_KEY no ambiente dele. Este exemplo lê as contas:

curl --fail-with-body -H "Authorization: Bearer $GCX_KEY" "$GCX_URL/api/v1/accounts"

O documento OpenAPI fica em $GCX_URL/api/v1/openapi.json. Um programa pede o documento com o mesmo cabeçalho Bearer; a descrição inclui só o que a chave dele pode chamar. Valores, preços e tamanhos são strings decimais.

De outro computador

Para um programa em outro computador, execute o conector lá no modo connect: enquanto ele roda, serve a sua instalação em um endereço local (pareamento). Pressione Exibir ao lado de Cursor e outros apps nesse computador e execute o conector com os valores do env dele (todos menos GCX_URL e GCX_KEY; seu programa envia a própria chave):

GCX_RELAY=… GCX_MAILBOX=… GCX_R=… GCX_PROFILE=… GCX_PAIR=… npx -y goodcryptox-connector@<version>-<build> connect --profile <the GCX_PROFILE value>

Ele imprime o endereço da conexão e depois o endereço da API terminado em /api/v1. Deixe-o rodando enquanto o programa usa a conexão e use o primeiro endereço como GCX_URL, por exemplo http://127.0.0.1:8130.

Inícios posteriores e mudanças de endereço

Nos inícios posteriores, execute npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>; o pareamento salvo é reutilizado. Cada instalação tem o próprio perfil e o próprio endereço. Se o endereço salvo estiver em uso, adicione --choose-new-address e depois copie o novo endereço no seu programa.

Enquanto está desconectado, as chamadas falham; elas não são guardadas para depois. Para conectar sem o nosso relay, use um túnel SSH.

Se você abre o goodcryptoX em um endereço doméstico, o Endereço do lado API é esse endereço: um programa na mesma rede envia as requisições para lá com a própria chave, sem o conector nem o nosso relay, e usa o endereço sem /api/v1 como GCX_URL. Use em uma rede em que confia ou pelo seu próprio endereço HTTPS confiável: em HTTP, alguém que consegue ler o tráfego pode copiar a chave.

Enviando uma ordem

Peça uma prévia primeiro (Conferindo uma ordem antes). Depois, POST /api/v1/orders com:

Em uma conta no Modo hedge, um mercado de futuros tem dois IDs, …:long e …:short, e o lado abre ou fecha: uma venda no long ou uma compra no short só reduz essa posição, com ou sem reduceOnly; reduceOnly: true no outro lado é recusado (reduce-only-opens).

Uma resposta perdida depois do envio não significa que uma ordem falhou: confira o resultado antes de tentar de novo. Ao repetir uma requisição de trading, mantenha o mesmo requestId e o mesmo corpo para que ela não possa colocar a mesma ordem duas vezes.

POST /api/v1/margin adiciona (um amount positivo) ou remove (um negativo) margem isolada de uma posição, na moeda de margem dela (MCP change_margin). Uma chave Operar faz isso nas contas e mercados que seus limites indicam, como ao definir a alavancagem: uma chave sem limites, ou de outra conta ou mercado, recebe 422 key.* e nada é enviado.

Os corpos das requisições e as mensagens de recusa de cada rota estão no documento OpenAPI em /api/v1/openapi.json.

Configurações que só você muda

Algumas rotas mudam algo que só você decide: uma chave que as chama recebe 403 person-only com uma frase para passar a você, e nada é enviado à exchange. As ferramentas MCP delas existem para que um agente possa dizer o que fazer.

  • POST /api/v1/accounts/{id}/bnb-fees ({"on": true}) liga ou desliga Pagar taxas em BNB em uma conta da Binance (MCP set_bnb_fees). A linha da conta em GET /api/v1/accounts mostra isso como bnbFees: on, e as configurações por trás, spot e usdm.

Retirando uma proposta

Uma chave que propôs uma ordem ou um bot pode retirá-la enquanto ela espera por você: POST /api/v1/proposals/{id}/withdraw com {"requestId": "..."}, escopo Propor ou acima. A resposta é {"accepted": true}; pedir de novo responde o mesmo. Uma proposta de outra chave responde 404, como se não existisse; uma que você lançou responde 422 proposal-launched, e uma que você rejeitou, 422 proposal-rejected. Rejeitar continua sendo seu: uma chave não pode rejeitar.

Pagar créditos com $GOOD

Os créditos são pagos da própria carteira da pessoa; um programa ou um agente só pode cotar, nunca pagar. POST /api/v1/credits/pay com build: false responde o que um pagamento adicionaria (esquema). Peça pelo valor da moeda, como o Adicionar créditos faz: input é o valor nas unidades da própria moeda, uma única chamada de rota, e o pagamento gasta exatamente isso. Na Solana, burn: true com qualquer moeda que não seja $GOOD compra $GOOD no mesmo pagamento e o queima, para obter o desconto do $GOOD:

O quote.credits da resposta são os créditos em USD e quote.goodMore quantos a mais do que os mesmos SOL comprariam sem $GOOD (aqui cerca de 9,90 e 0,90). Com token sendo o próprio mint do $GOOD, o $GOOD que você tem é queimado (sem burn). amount (créditos desejados) e spend (USD a gastar nos caminhos com $GOOD) continuam aceitos.

Na Tron, o TRX é trocado por USDT no pagamento; qualquer outro TRC-20 responde no-route.

Totais do histórico de créditos

Depois que a pessoa paga, POST /api/v1/credits/pay/receipt com o {chain, id} do pagamento lê o status dele em qualquer uma das nossas redes; os créditos costumam aparecer em GET /api/v1/credits segundos depois da primeira confirmação, e um pagamento que a rede descarta depois é retirado por uma linha do histórico com reason: "reversed" (abaixo de zero, com o chain e o tx dele, e o token, o amount e o seq do pagamento em payment).

GET /api/v1/credits e a ferramenta MCP credits retornam o mesmo objeto adicional opcional totals (esquema). totalPaid, paymentCredits, grants, totalVolume, totalFees, dailyVolume, dailyFees, monthlyVolume, monthlyFees e balanceDifference são strings decimais em USD. firstDay é a data UTC da primeira operação registrada ou null, throughDay é a data UTC de hoje e dayCount conta os dois extremos e os dias sem operações. As médias mensais são trinta vezes as diárias, mesmo com dez dias de histórico ou na virada do mês. paidEstimated marca custos deduzidos de pagamentos. balanceDifference = paymentCredits + grants - totalFees - balance; um valor diferente de zero avisa, nunca bloqueia. Pagamentos pendentes e revertidos são excluídos; um pagamento descartado pela rede sai de totalPaid e paymentCredits pela sua linha reversed, e nunca conta em grants. Se uma versão anterior não tiver totais, use os dias e o histórico conhecidos e informe que os valores são parciais. days e a paginação ?before=YYYY-MM-DD não mudam. Pagar pela carteira continua sendo uma ação da pessoa. Só os valores completos podem indicar uma diferença no saldo. O custo em dinheiro de cada pagamento com $GOOD é estimado.

Volume de trading

Use GET /api/v1/trading-volume?before=YYYY-MM-DD com permissão de leitura, ou consulte a ferramenta MCP trading_volume. Ela mostra quanto você negociou em USD, quantas negociações foram executadas, as taxas pagas e o PnL realizado, por conta, mercado e por quem enviou a ordem, desde que você conectou cada conta à goodcryptoX. Veja o esquema da resposta.

totals abrange todas as negociações que guardamos. days mostra os últimos 31 dias UTC com negociações, do mais recente ao mais antigo. Para obter a próxima página, passe next como before; esse dia fica fora da próxima página. Os valores são strings decimais em USD. Funding, transferências e ordens não executadas não contam. O PnL realizado em spot não entra nesses totais. As taxas da exchange e as da goodcryptoX ficam separadas; um reembolso de taxas é negativo.

manual indica uma ordem enviada por uma pessoa ou uma chave de acesso. dca e grid indicam ordens de bots. gcx significa que sabemos que a ordem passou pela goodcryptoX, mas já não sabemos de que tipo era nem a quem pertencia a chave que a enviou. external inclui negociações feitas fora da goodcryptoX, liquidações e desalavancagem automática.

Confira o state e o reason de cada conta antes de considerar seus totais completos. Negociações de antes de você conectar uma conta não são contadas. Uma conta que você removeu mantendo o histórico e depois recolocou mantém o que já tinha contado e volta a contar a partir da recolocação. since é o momento da negociação mais antiga que guardamos, em milissegundos; não garante que todas as negociações posteriores estejam presentes. Se a leitura do histórico falhar, a conta continua incompleta até uma nova tentativa dar certo. Uma conta recém-conectada fica pendente enquanto lemos as negociações desde a sua conexão. Na Binance, contamos as negociações feitas fora da goodcryptoX enquanto a goodcryptoX está em execução. Podem faltar negociações feitas quando ela estava desligada ou perdidas durante uma falha, principalmente em mercados que não conhecíamos.

missing conta as negociações que não conseguimos avaliar totalmente em USD: uma taxa numa moeda para a qual a exchange não nos deu preço, ou uma negociação num mercado que ainda não conhecíamos. O que não conseguimos avaliar contribui com zero; uma negociação num mercado que ainda não conhecíamos fica assim. estimated conta as negociações avaliadas com uma cotação que tínhamos guardado em vez de um preço do momento da execução. Guardamos os valores originais para poder melhorar esses números depois. unknownFees conta as negociações cuja taxa da exchange é desconhecida, incluindo negociações de ações. unknownPnl conta as negociações de perpétuos cujo PnL realizado é desconhecido, em vez de sabidamente zero. Os campos de recuperação mostram até onde verificamos o histórico salvo. Para a pessoa, unmatchedFees conta os débitos de créditos que não conseguimos vincular a uma negociação guardada.

Uma chave só vê as contas conectadas que tem permissão para ler. Ela vê seu próprio keyId; os números de outras chaves e da pessoa são agrupados sem seus identificadores. Os números de demo e as contas apagadas ficam de fora. Uma data que não existe retorna 400.

Identidades do portfólio

GET /api/v1/portfolio e a ferramenta MCP somente leitura portfolio acrescentam assets ao lado dos suplementos de conta, snapshots e PnL já existentes. Cada ativo tem assetId, assetKind (bundled ou exchange), symbol, name, amount, value, unpriced e holdings. bundled é uma identidade explícita do registro, mesmo que hoje esteja em uma só conta. exchange é um ativo de exchange sem correspondência; o id dele inclui a exchange e o código exato do ativo. Nunca junte linhas por symbol.

holdings mantém cada conta, exchange, código original, quantidade, preço, valor e a marca de preço ausente. Valores e preços são strings decimais em USD. As quantidades estão nas unidades daquele ativo; quantias de carteira que só têm valor são nulas. O valor de um grupo soma os valores dos ativos: 2 UBTC a 60.000 em uma exchange mais 1 BTC a 61.000 em outra dá 181.000, e não três vezes um preço de referência. Sem preço, a quantidade permanece e o valor contribui zero; unpriced é verdadeiro se algum componente não tiver preço. Os preços são os mais recentes conhecidos no goodcryptoX local; esta leitura não inventa um preço nem exige um serviço da goodcryptoX. Contas excluídas dos saldos e dinheiro de demonstração não aparecem nos totais de ativos conectados. Versões mais antigas omitem assets; todos os campos antigos mantêm o significado.

O pnl da resposta é o que as contas ganharam desde que foram conectadas à goodcryptoX, pelo próprio registro da goodcryptoX, igual em todas as exchanges: negociações de futuros fechadas depois das taxas, e funding. Cada linha de accounts traz connected, o momento a partir do qual conta o PnL daquela conta; nada anterior entra em nenhum período.

Perguntas

Existe um documento OpenAPI?

Sim: em /api/v1/openapi.json no endereço da sua instalação, pedido com o mesmo cabeçalho Bearer. Ele descreve só o que a chave pode chamar.

A API funciona de outro computador?

Sim: execute o conector lá no modo connect e, enquanto ele roda, serve a sua instalação em um endereço local. Um túnel SSH também funciona.

Um programa pode colocar ordens?

Sim, com uma chave Operar: POST /api/v1/orders, dentro das contas, dos mercados e dos limites da chave. Peça uma prévia primeiro; ela não envia nada.

O que acontece se a minha requisição expirar?

Uma resposta perdida não significa que uma ordem falhou: confira o resultado antes de tentar de novo. Ao repetir, mantenha o mesmo requestId e o mesmo corpo para que ela não possa colocar a mesma ordem duas vezes.

Última atualização