> For the complete documentation index, see [llms.txt](https://docs.goodcrypto.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/api.md).

# API

Leia e opere pela API local do goodcryptoX a partir do seu próprio programa, com as mesmas chaves e limites de um agente de IA.

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](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) lê novamente as permissões da chave API de uma conta Binance, Bybit ou Bybit EU, assim como **Verificar novamente** no cartão dela.

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](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket). 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](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)); 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.

<details>

<summary>Exemplo de requisição à API</summary>

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:

```sh
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.

</details>

As contas demo e a visualização Bybit para desenvolvedores, incluindo exemplos de envio com chave somente leitura e recuperação, são para pessoas conectadas ao painel. Chaves de acesso e MCP não podem usar `demoBybitView` nem `demo=1`.

## De outro computador <a href="#from-another-computer" id="from-another-computer"></a>

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](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/ai-agents.md#from-another-computer)). 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):

```sh
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`.

<details>

<summary>Inícios posteriores e mudanças de endereço</summary>

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.

</details>

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](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Se você abre o goodcryptoX em um [endereço doméstico](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network), 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 <a href="#sending-an-order" id="sending-an-order"></a>

Peça uma prévia primeiro ([Conferindo uma ordem antes](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). Depois, `POST /api/v1/orders` com:

```json
{
  "requestId": "my-strategy-0001",
  "sourceId": "YOUR-ACCOUNT-ID",
  "instrumentId": "ETH",
  "type": "limit",
  "side": "buy",
  "size": "90",
  "sizeUnit": "quote",
  "price": "3000",
  "overrides": [],
  "bracket": {
    "reduceOnly": true,
    "tp": { "type": "market", "mode": "percent", "targets": [{ "value": "3", "share": "100" }] },
    "sl": { "type": "market", "mode": "percent", "value": "1.5" }
  }
}
```

Se a alavancagem da conta ainda não foi lida, a ordem de um perpétuo é enviada e a exchange aplica sua própria alavancagem; o recibo da prévia não traz então dados de fundos, e a margem não foi verificada.

Uma ordem com tamanho na moeda de cotação (`"sizeUnit": "quote"`, ou `"coin"` em um contrato com margem em moeda) mantém esse valor: as moedas são recalculadas a cada envio, pelo preço de envio (uma ordem limite pelo seu preço, após cada mudança de preço; um stop quando dispara). A linha mostra o valor como `cost` e `sizeUnit` ao lado de `size`, a quantidade atual em moedas. Um valor igual ou superior ao mínimo da exchange é arredondado um passo de tamanho para cima se arredondá-lo para baixo o deixaria abaixo do mínimo; assim, `size` na linha pode valer até um passo a mais que o valor enviado. Um tamanho maior que zero que não enviaria nada (abaixo de um passo de tamanho após esse arredondamento) é colocado como um passo da moeda, e a resposta indica isso: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}`; zero é recusado. Para alterar, `POST /api/v1/orders/{id}/modify` (MCP `modify_order`) aceita `changes.sizeUnit` com `size`: `{"size": "150", "sizeUnit": "quote"}` define o valor em 150, `{"price": "2900"}` mantém o valor no novo preço e `size` sozinho indica moedas.

Uma ordem abaixo do valor mínimo da exchange é enviada como você a envia (a prévia avisa com `trade.msgMinNotional`); o resultado é a resposta da exchange. Os bots fazem o mesmo: a entrada e as ordens de média de um bot DCA e os níveis de um Grid abaixo do mínimo são enviados, e uma ordem recusada pela exchange vira uma ordem com falha do bot (um nível DCA `failed`, a contagem `failed` de um Grid), enviada de novo por Tentar de novo ou Repetir falhas. A linha do recibo da prévia do bot marca essa ordem como `under`; `sent` false indica apenas uma ordem pequena demais para ser enviada. Uma linha Grid com `sendAll` coloca todos os níveis; uma sem ele (iniciada por uma versão anterior) retém os níveis abaixo do mínimo.

Em um mercado com margem em moeda (`contract.method` `"DIV"`), os tamanhos de ordens, posições e bots são retornados em contratos junto com os dados do contrato: USD = contratos × `contract.multiplier`, e a moeda = esses USD ÷ preço. Um bot DCA com `"sizingMode": "coin"` recebe `entryAmount` e `level1Amount` na moeda de liquidação do contrato (`contract.settlement`): cada ordem é essa quantidade de moeda ao próprio preço, arredondada para baixo a contratos inteiros. `"cost"` usa os mesmos USD em cada ordem; um valor em USD abaixo de um contrato começa com o valor em USD de um contrato, e cada nível é escalado a partir dele.

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 Hyperliquid, Binance e Bybit, na moeda de margem dela (MCP `change_margin`). A Bybit EU oferece apenas spot. 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 <a href="#settings-only-you-change" id="settings-only-you-change"></a>

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`.

O interruptor **Garantia** de uma moeda também é só seu: `POST /api/v1/accounts/{id}/collateral` responde 403 a uma chave e não tem ferramenta MCP. Um programa lê a configuração no tópico `balances` (`perCoinCollateral`: a carteira e, para cada moeda, `accepted`, `selected` e `fixed`; null significa desconhecido, nunca desativado), ou lê uma moeda na exchange naquele momento com `GET /api/v1/accounts/{id}/collateral?coin=BTC` (`{coin, accepted, selected}`; 503 quando a leitura falha ou leva mais de dez segundos).

Só você pode remover contas: `POST /api/v1/accounts/{sourceId}/remove` também atende Binance, Bybit e Bybit EU; não há ferramenta MCP para remover contas.

## Retirando uma proposta <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

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.

## Listas de várias contas <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions` e `GET /api/v1/lists/orders` leem todas as contas abrangidas pela lista. Uma conta que a exchange não conseguiu ler não esconde as outras: o `state` da página continua `live` enquanto alguma conta tiver sido lida, e `accountStates` informa o estado de cada uma (`live`, `stale`, `unavailable` ou `waiting` na primeira leitura), para você saber de quem podem faltar linhas. O `state` da página só é `stale` ou `unavailable` quando nenhuma conta pôde ser lida. Cancelar todas, Parar todos e Fechar todas respondem por cada ordem, bot ou posição separadamente: o que falha aparece em `refused` com sua mensagem, e o restante é contado em `count` e `ids`.

## As ordens que falharam em um bot <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

Uma ordem de preço médio do DCA ou uma ordem do grid que é recusada não para o bot, então não aparece nem nas linhas de atenção nem nos `items` do bot; ali só entra o que para um bot ou espera por você. Leia as ordens de média que falharam de um bot DCA em `counters.averagingFailed` da linha dele, as de um grid em `failed` (próxima seção), e cada ordem que falhou na linha da ordem: `why` é a frase que o painel mostra, `errorType` o tipo por trás dela e `exchangeWords` as palavras da própria exchange; as ferramentas MCP leem as mesmas linhas. `errorType` é uma string aberta: mostre os tipos que você conhece e aceite valores novos. `exchangeWords` guarda a mensagem `text` da exchange e, se houver, `code`; `reason` guarda a resposta original. Os dois campos não existem sem uma recusa da exchange e em runtimes mais antigos.

Uma ordem que falhou de um bot e que o bot enviaria de novo agora traz `retry: true`: a pessoa pode apertar **Tentar de novo** nessa ordem. Uma chave não consegue enviá-la (`restore-level` não está entre os comandos de bot de uma chave), então avise a pessoa. Em um bot DCA é uma ordem de média; sem `retry` o bot a recusaria: está pausado, em reparo, depois que o stop-loss disparou, enquanto o take profit acompanha, ou é uma tentativa anterior do nível. Em um grid é a linha de ordem da última tentativa de uma ordem que falhou, e a linha da ordem que falhou em `orders` da linha do grid também a traz, com `error` (nossa frase `why` e, quando a exchange recusou, `errorType` e `exchangeWords`) e `past: true` enquanto colocá-la de novo a executaria na hora. Sem `retry` o grid não a colocaria: está pausado, parando, sua posição difere da da exchange, um item retém suas novas ordens, o resultado da tentativa não é conhecido ou outra ordem ocupa aquele nível. Tentar de novo em uma ordem do grid é **Repetir falhas** para aquela ordem: uma leitura do que está livre, e a resposta é a de Repetir falhas, `{"placed", "left", "needed", "unit"}`, para aquela ordem.

## O que um bot precisa da sua conta <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

Em perpétuos, `ownFunds` na linha de um bot é o que o bot precisa da sua conta para chegar ao stop (o stop loss de um DCA) ou, sem stop, para executar a última ordem de média, taxas incluídas: o número que `margin.survive` (`margin.toLast`) da prévia deu quando o ciclo foi dimensionado. Um ciclo de DCA de uma versão anterior mantém o valor das suas ordens ÷ a sua alavancagem. O de um grid é calculado quando a linha é servida, inclusive nos grids encerrados. `invested` (Máx. previsto) é o plano do maior ciclo; um bot que ainda não tem ciclo mostra o plano com que vai começar. Um bot dimensionado como porcentagem da conta é dimensionado para que a sua necessidade seja essa porcentagem: um DCA em execução a partir do próximo ciclo, um grid a partir da próxima ordem que coloca.

## As ordens que falharam em um grid <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

Uma linha de grid em `GET /api/v1/bots` traz `failed`, o número de ordens que falharam, e, enquanto for maior que zero, `failedWhy`: `money` quando todas foram recusadas ou canceladas por falta de fundos, `other` quando nenhuma foi, `mixed` nos demais casos. A leitura das ordens lista cada ordem que falhou com seu status.

`POST /api/v1/bots/{id}/command` com `{"requestId": "...", "kind": "fix-failed"}` as coloca de novo, como **Repetir falhas** no painel: uma nova leitura do que a exchange diz estar livre para uma nova ordem, menos suas ordens a caminho, depois as ordens que falharam mais próximas do preço primeiro, até onde der. Não envia nada que a leitura não cubra. A resposta é `{"placed", "left", "needed", "unit"}`: quantas enviou, quantas ainda estão com falha e quanto mais de `unit` falta para o restante (uma ordem que a exchange recusar depois volta a aparecer em `failed` da linha); `later` conta as deixadas por outro motivo, `past` as enviadas na hora porque o preço já as havia ultrapassado. Um grid pausado responde 422 `paused` e não coloca nada; uma leitura de saldo que falha responde 422 `balance` e não coloca nada; um grid parado responde 409 `state`. É uma ação de ordem, então uma chave pode enviá-la para um grid que criou. Os problemas do bot não trazem mais um item `orders-failed`; o `facts.failed` dele está obsoleto (veja As ordens que falharam em um bot). A ferramenta MCP usa a mesma operação.

Um bot que ainda está parando ou iniciando cinco minutos depois de começar, sem esperar nada que você definiu, traz um item com a causa `stuck-stopping`, `stuck-launching` ou `stuck-entry` (uma entrada DCA não executada); `GET /api/v1/bots/{id}` e as linhas de atenção do Dashboard o servem, e ele some quando o bot sai desse estado.

## Pagar créditos com $GOOD <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

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](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). 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:

```json
{"chain":"solana","token":"native","input":"0.1007","burn":true,"payer":"<the wallet's address>","build":false}
```

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`.

Na resposta, `quote.feeKept` é quanto da moeda nativa da rede o pagamento deixa para a taxa, nessa moeda (redes EVM e Tron).

## Totais do histórico de créditos <a href="#credits-history-totals" id="credits-history-totals"></a>

Depois que a pessoa paga, `POST /api/v1/credits/pay/receipt` com o `{chain, id}` do pagamento (e `coin`, o ticker com que foi pago, que o item do histórico do pagamento passa então a trazer como `paidWith`) 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`). O `token` de um pagamento é a moeda que chegou (após um swap, o token de dólar) e os valores dele estão nela; `paidWith`, quando presente, é a moeda com que a pessoa pagou (TRX, ETH, SOL), a que a linha de Pagamentos nomeia; ausente (um pagamento feito antes deste campo, ou enviado de fora do app), nomeie `token`.

`GET /api/v1/credits` e a ferramenta MCP `credits` retornam o mesmo objeto adicional opcional `totals` ([esquema](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `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 <a href="#trading-volume" id="trading-volume"></a>

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](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json).

`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 <a href="#portfolio-identities" id="portfolio-identities"></a>

`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.

Lê os números das posições pelo tópico `positions` (`snapshot` no MCP). `GET /api/v1/funding?sourceId=&instrumentId=` e a ferramenta MCP somente de leitura `funding` devolvem pagamentos com sinal e a parte de cada bot. O campo opcional `id` identifica o pagamento da exchange; `asset` é a moeda indicada pela exchange para o valor do campo antigo `usdc`. Nunca presumas que esse valor está em USDC. Os pagamentos da Binance no modo hedge ficam na conta porque a exchange não informa o lado. Compatibilidade: as linhas antigas omitem `id` e `asset`; os campos existentes mantêm o significado.

## Perguntas <a href="#questions" id="questions"></a>

### Existe um documento OpenAPI? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

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? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

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](https://docs.goodcrypto.app/goodcryptox-pt/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead) também funciona.

### Um programa pode colocar ordens? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

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? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

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.
