> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/pt-br/guides/portfolio.md).

# Portfólio e estado da conta

Estado consolidado da conta, saldo disponível para saque, tabela de taxas, posições enriquecidas e a série temporal do portfólio, nos SDKs e na CLI.

Os endpoints de portfólio respondem a quatro perguntas sobre uma conta: quanto ela vale agora, o que pode ser sacado, quanto ela paga em taxas e como foi seu desempenho ao longo do tempo. Eles são um pequeno conjunto de endpoints REST autenticados, mais campos de risco enriquecidos por posição. Toda interface (os SDKs Rust, TypeScript e Python e a CLI) acessa as mesmas rotas no gateway documentado em [APIs e limites](https://docs.nexus.xyz/exchange/apis-and-rates).

Se você está construindo uma visão de portfólio, leia [Ler esses valores com segurança](#reading-these-values-safely) antes de renderizar qualquer coisa. Vários campos são anuláveis de propósito, uma convenção de sinal é fácil de inverter, e uma implementação ingênua com duas chamadas vai esbarrar em uma condição de corrida em produção.

### Como obter

```bash
npm install @nexus-xyz/exchange-ts    # TypeScript
cargo add nexus-exchange              # Rust
pip install nexus-exchange            # Python
```

A CLI é distribuída pelos releases de [`nexus-exchange-cli`](https://github.com/nexus-xyz/nexus-exchange-cli). Consulte a [Visão geral das interfaces](/api-reference/pt-br/readme.md) para os quatro clientes.

### Autenticação

Toda rota desta página tem escopo de conta e exige uma chave de API HMAC. Não existe variante pública ou sem autenticação. As requisições carregam `X-API-Key`, `X-Timestamp` e `X-Signature`, e o timestamp precisa estar a até 30 segundos do horário do servidor. Os SDKs e a CLI assinam por você. O fluxo completo, com cURL executável, está no [Guia rápido](https://docs.nexus.xyz/exchange/trading/quickstart).

Mantenha o segredo da API fora do código-fonte e fora do histórico do shell. Ele é exibido uma única vez na criação e não pode ser recuperado depois. Os exemplos abaixo o leem do ambiente.

### Escolher uma rede

A Exchange roda hoje na Nexus Testnet, e a mainnet virá depois. Selecione a rede quando construir o cliente. Consulte [Redes](/api-reference/pt-br/guides/networks.md) para ver como cada interface faz isso e como as chaves de API se vinculam a uma rede, e [APIs e limites](https://docs.nexus.xyz/exchange/apis-and-rates) para a URL base atual. A chave HMAC que essas rotas exigem fica restrita à rede em que foi criada.

### Referência

| Método | Caminho                                     | Autenticação | Descrição                                                                             |
| ------ | ------------------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
| GET    | `/account/state`                            | HMAC         | Resumo do portfólio **e** todas as posições abertas, a partir de uma leitura coerente |
| GET    | `/account/summary`                          | HMAC         | Apenas o resumo do portfólio, o mesmo objeto incorporado em `/account/state`          |
| GET    | `/account/fees`                             | HMAC         | Tabela de taxas efetiva da conta                                                      |
| GET    | `/account/portfolio-history?window=&limit=` | HMAC         | Série temporal de patrimônio, PnL acumulado e volume acumulado                        |

Pontos de entrada por SDK:

| Interface  | Estado consolidado      | Tabela de taxas        | Série temporal                                     |
| ---------- | ----------------------- | ---------------------- | -------------------------------------------------- |
| Rust       | `fetch_account_state()` | `fetch_account_fees()` | `fetch_portfolio_history(window, limit)`           |
| Python     | `fetch_account_state()` | `fetch_account_fees()` | `fetch_portfolio_history(window, limit)`           |
| TypeScript | `getAccountState()`     | `getAccountFees()`     | `getPortfolioHistory({ window, limit })`           |
| CLI        | `nexus account state`   | `nexus account fees`   | `nexus account portfolio-history --window --limit` |

### Estado consolidado da conta

`GET /account/state` retorna os agregados do portfólio e todas as posições abertas construídos a partir de **uma** leitura no servidor. Como as duas metades vêm do mesmo snapshot, `summary.open_positions_count` é sempre igual ao comprimento de `positions`.

O resumo carrega `collateral`, `total_equity`, `total_unrealized_pnl`, `total_realized_pnl_24h`, `total_volume_24h`, `open_positions_count`, `open_orders_count`, `margin_used`, `available_margin` e `withdrawable`.

**`withdrawable`** é o saldo que pode sair da conta: a margem livre autoritativa do motor, com piso em zero, `max(0, available_margin)`. A margem livre já desconta do patrimônio a margem inicial de cada posição e toda reserva pré-negociação de ordens, então este é o valor do qual um saque pode dispor. Não é `total_equity`, nem `collateral`. Uma conta no negativo é limitada a `"0"` e nunca é reportada como negativa. O valor vem da visão de margem autoritativa, então, quando essa visão está indisponível, o endpoint **falha de forma fechada com `502`** em vez de retornar um número estimado localmente.

### Tabela de taxas

`GET /account/fees` informa o que a plataforma cobra da conta hoje. Essa é a taxa prospectiva da tabela, não uma média realizada sobre execuções passadas.

| Campo                  | Observações                                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `maker_fee_bps`        | Pontos-base principais. Pode ser negativo; zero é uma sentinela quando `schedule=unknown`                          |
| `taker_fee_bps`        | Pontos-base principais; zero é uma sentinela quando `schedule=unknown`                                             |
| `tier`                 | Atualmente sempre `base`; ainda não há níveis por conta                                                            |
| `schedule`             | `per_market`, `reference` ou `unknown`; trate como uma string aberta                                               |
| `markets`              | Taxas dos mercados no buffer de execuções retido; ordenado por `market_id`                                         |
| `volume_30d`           | Valor nocional negociado nos últimos 30 dias (janela móvel), string decimal. Melhor esforço, veja a flag abaixo    |
| `volume_30d_estimated` | `true` quando `volume_30d` pode estar **subcontado** (o buffer de execuções de origem estava na capacidade máxima) |
| `discounts`            | Descontos ativos. Atualmente sempre vazio                                                                          |

Quando `schedule` é `per_market`, use as linhas de `markets` retornadas como as taxas autoritativas. O par de nível superior é apenas o resumo modal determinístico delas. O buffer de execuções em memória, com limite de tamanho, pode ser reiniciado ou descartar mercados antigos, então uma linha ausente não é evidência de que a conta nunca negociou naquele mercado. `reference` significa que o buffer retido não tem nenhum mercado com tabela espelhada e que o par de nível superior é a taxa modal determinística entre todos os mercados espelhados da plataforma. Nos dois cálculos modais, vence o par com a maior contagem de ocorrências, e empates são resolvidos para o par `(maker_fee_bps, taker_fee_bps)` lexicograficamente menor. `unknown` significa que os parâmetros de mercado estão indisponíveis. `markets` fica vazio e os dois valores de bps principais são sentinelas zero, não uma tabela sem taxas. Hoje não existe nenhum programa de níveis ou descontos por conta. Trate `schedule` como aberto e não crie ramificações para um formato de desconto que não existe.

### Série temporal do portfólio

`GET /account/portfolio-history` retorna patrimônio, PnL de negociação acumulado e valor nocional negociado acumulado ao longo de uma janela, com downsampling no servidor. Os pontos vêm **do mais antigo para o mais recente**.

| `window` | Cadência | Máx. de pontos | Período |
| -------- | -------- | -------------- | ------- |
| `day`    | 5 min    | 288            | 24 h    |
| `week`   | 1 h      | 168            | 7 d     |
| `month`  | 6 h      | 120            | 30 d    |
| `all`    | 1 d      | 366            | \~1 y   |

Omitir `window` resulta em `day`. Um valor fora desse conjunto é rejeitado com `400` (`invalid_window`). Se o parâmetro for repetido, o primeiro valor é usado. `limit` precisa estar entre `1` e `366`. Dentro desse intervalo, ele restringe o resultado e é **limitado** à capacidade da janela em vez de rejeitado, então pedir 366 pontos de `day` retorna 288 em vez de um erro. Fora desse intervalo, a requisição é rejeitada com `400`.

A resposta ecoa a `window` e o `cadence_ms` que foram servidos. Leia-os de volta em vez de presumir os valores que você enviou, para que os eixos do seu gráfico usem os valores servidos.

Cada ponto carrega `timestamp_ms`, `equity`, `pnl` e `volume`. `pnl` e `volume` são **acumulados até aquela amostra**, não por intervalo. Para mostrar a atividade por intervalo em um gráfico, calcule você mesmo a diferença entre pontos adjacentes.

### Campos de posição enriquecidos

As posições retornadas por `/account/state` (e `/positions`) carregam detalhes de risco por posição junto com `symbol`, `side`, `size`, `entryPrice`, `unrealizedPnl` e `realizedPnl`:

| Campo           | Significado                                                                    |
| --------------- | ------------------------------------------------------------------------------ |
| `notional`      | `abs(size) × mark price`                                                       |
| `initialMargin` | Margem inicial mantida contra a posição, no modelo de margem cruzada           |
| `roe`           | Retorno sobre a margem inicial: `unrealizedPnl / initialMargin`                |
| `max_leverage`  | Alavancagem máxima que o mercado permite, a partir de seus parâmetros de risco |
| `leverage`      | O multiplicador de alavancagem da conta para esta posição                      |
| `funding_paid`  | Financiamento acumulado da posição. Veja a convenção de sinal abaixo           |

**Os nomes são o vocabulário unificado do CCXT**, então um cliente `ccxt.nexus()` lê esse formato diretamente. Os campos sem equivalente no CCXT mantêm a grafia própria da plataforma: `size`, `roe`, `max_leverage`, `funding_paid`. `GET /account` não tem esse formato. Ele é repassado pelo motor de matching e responde com um objeto mais restrito, sob os nomes próprios do motor.

O servidor calcula esses campos no caminho de leitura de baixa latência em vez de fazer uma ida e volta ao motor de matching, o que mantém o endpoint rápido. A contrapartida é que, quando um dos insumos não está disponível nesse caminho, o campo é `null` e um `<field>_error` companheiro carrega um motivo legível por máquina em vez de um número fabricado.

**`leverage` é atualmente sempre `null`,** com `leverage_error` definido como `margin_state_not_mirrored`. Derivá-lo exige a configuração de alavancagem da conta ou sua margem alocada, e nenhuma das duas está disponível no caminho de leitura. Não o reconstrua a partir de `initialMargin`. Essa expressão se reduz a `1 / initial_margin_rate`, que é uma constante por mercado e não a alavancagem real da posição, então estaria errada para todas as posições do mercado.

**`funding_paid` é positivo quando pago.** Um valor positivo significa que a posição *pagou* financiamento, e um valor negativo significa que ela *recebeu* financiamento. Ele está sempre presente, é `"0"` antes de qualquer financiamento acumular, e fica limitado pelo histórico de financiamento que a plataforma retém. Inverter esse sinal transforma um custo em receita numa tela de P\&L, então escreva um teste para isso.

### Ler esses valores com segurança

**Valores monetários são strings decimais, não números.** `equity`, `pnl`, `volume`, `withdrawable`, `notional` e os demais são decimais de precisão arbitrária serializados como strings para não perder precisão. Faça o parse deles com um tipo decimal. Passá-los por um float (`parseFloat`, `float()`, `as f64`) reintroduz o erro de arredondamento que a codificação em string existe para evitar. Os campos de alavancagem (`leverage`, `max_leverage`) são números JSON de fato.

**Campos derivados têm três estados, não dois.** Cada um dos cinco campos de posição calculados (`notional`, `initialMargin`, `roe`, `leverage` e `max_leverage`) pode ser:

1. **um valor**: calculado e autoritativo;
2. **`null`**: reportado, mas não calculável, e o `<field>_error` correspondente diz por quê;
3. **ausente**: o servidor é anterior ao campo.

Reduzir qualquer um deles a `0` inventa dados. "Não reportado", "não calculável" e "zero" são três respostas diferentes para um usuário que pergunta quanto vale sua posição, e só uma delas é um número. Renderize os casos ausentes como uma lacuna explícita (a CLI imprime `-`) e exiba o `<field>_error` quando você o tiver. O mesmo vale para `withdrawable`. Ele é opcional no schema, então uma implantação mais antiga pode omiti-lo, e usar `"0"` como padrão diria a alguém que não tem nada disponível quando o servidor nunca reportou o valor.

Esses cinco são exatamente os campos que têm um `<field>_error` companheiro. `funding_paid` não é um deles. Ele está sempre presente, então não existe `funding_paid_error` para verificar.

**Prefira `/account/state` a duas chamadas.** Buscar `/account/summary` e `/positions` separadamente são duas requisições independentes contra uma conta ativa. Uma execução que ocorra entre elas retorna um agregado que discorda da lista de posições (`open_positions_count` diz três, o array tem quatro), e isso acontece sob qualquer carga real. O endpoint consolidado sustenta as duas metades com uma leitura coerente.

**Trate os códigos de falha de forma distinta.** `401` é um problema de credencial ou de relógio. Verifique se o `X-Timestamp` está a até 30 segundos do horário do servidor antes de presumir que a chave está errada. `429` significa que você excedeu o orçamento de requisições; consulte [Limites de requisições](/api-reference/pt-br/guides/rate-limits.md) e recue em vez de tentar novamente de imediato. Três rotas desta página (`/account/summary`, `/fills` e `/account/portfolio-history`) custam **cinco** unidades desse orçamento cada, em vez de uma, então consultá-las em um loop apertado esgota a cota de 20/s de um chamador Pro cinco vezes mais rápido do que a contagem de requisições sugere. `/account/state` custa uma e retorna o resumo e as posições juntos, que é a forma mais barata de ler ambos. `502` em `/account/state` e `/account/summary` significa que a visão de margem autoritativa estava inacessível e o servidor se recusou a adivinhar. Tente novamente e não recorra a um `withdrawable` calculado localmente.

### Exemplo

```bash
export NEXUS_API_KEY=nx_7f3a1b...          # the key ID is not secret

# Prompt for the secret instead of typing it inline — an `export
# NEXUS_API_SECRET=...` would leave it in your shell history.
read -rs NEXUS_API_SECRET && export NEXUS_API_SECRET

nexus account state
nexus account fees
nexus account portfolio-history --window week
```

```typescript
import { Client, Network } from "@nexus-xyz/exchange-ts";

const client = new Client({
  network: Network.Testnet,
  apiKey: process.env.NEXUS_API_KEY!,
  apiSecret: process.env.NEXUS_API_SECRET!,
});

// One coherent read: open_positions_count cannot disagree with positions.length.
const { summary, positions } = await client.getAccountState();

// Absent is not zero — say so rather than defaulting.
console.log(`withdrawable: ${summary.withdrawable ?? "<not reported>"}`);

for (const p of positions) {
  // null carries a reason in the companion field; absent carries nothing.
  const roe = p.roe ?? (p.roe_error ? `<${p.roe_error}>` : "<not reported>");
  // Paid-positive: a positive funding_paid means this position paid.
  console.log(`${p.symbol} ${p.side} ${p.size}  roe=${roe}  funding_paid=${p.funding_paid}`);
}

// The response echoes what was served — read it back, don't assume.
const history = await client.getPortfolioHistory({ window: "week" });
console.log(`${history.window} @ ${history.cadence_ms}ms, ${history.points.length} points`);
```

```json
{
  "summary": {
    "collateral": "25000.00",
    "total_equity": "25500.00",
    "total_unrealized_pnl": "500.00",
    "margin_used": "1075.00",
    "available_margin": "24425.00",
    "withdrawable": "24425.00",
    "open_positions_count": 1,
    "open_orders_count": 0
  },
  "positions": [
    {
      "symbol": "BTC-USDX-PERP",
      "side": "Long",
      "size": "0.25",
      "entryPrice": "84000.00",
      "unrealizedPnl": "500.00",
      "notional": "21500.00",
      "initialMargin": "1075.00",
      "roe": "0.4651",
      "max_leverage": 20,
      "leverage": null,
      "leverage_error": "margin_state_not_mirrored",
      "funding_paid": "3.21"
    }
  ]
}
```

Os números acima são coerentes entre si. A um preço de marca de `86000`, `notional` é `0.25 × 86000`, `unrealizedPnl` é `0.25 × (86000 − 84000)`, `initialMargin` é `notional × 1/max_leverage`, `roe` é `unrealizedPnl / initialMargin`, e `withdrawable` é igual a `total_equity − margin_used` do resumo, porque não há ordens abertas reservando margem. Observe as duas grafias nessa última cláusula. `margin_used` no objeto SUMMARY é o agregado da conta e mantém seu nome. `initialMargin` em uma posição é o requisito por posição.

Exemplos executáveis de ponta a ponta estão nos repositórios dos SDKs: [`examples/portfolio.ts`](https://github.com/nexus-xyz/nexus-exchange-ts/blob/main/examples/portfolio.ts) e [`examples/portfolio.rs`](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/examples/portfolio.rs).

### Relacionados

* [APIs e limites](https://docs.nexus.xyz/exchange/apis-and-rates)
* [REST da Exchange](https://docs.nexus.xyz/exchange/apis-and-rates/exchange-rest)
* [Limites de requisições](/api-reference/pt-br/guides/rate-limits.md)
* [Visão geral das interfaces](/api-reference/pt-br/readme.md)
* [Guia rápido](https://docs.nexus.xyz/exchange/trading/quickstart)

> **Status:** prévia de desenvolvimento na testnet. Essas rotas estão presentes na especificação OpenAPI v0.7.2 e seguem atuais na v0.9.90. Fixe uma versão da especificação em produção e verifique as notas de release de cada SDK antes de atualizar. `/account/fees` não tem programa de níveis ou descontos por conta hoje, e `leverage` reporta `null` até que o estado de margem de que ele precisa seja espelhado. Credenciais e saldos da testnet não têm valor no mundo real.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/pt-br/guides/portfolio.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.