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.
Se você está construindo uma visão de portfólio, leia Ler esses valores com segurança 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
npm install @nexus-xyz/exchange-ts # TypeScript
cargo add nexus-exchange # Rust
pip install nexus-exchange # PythonA CLI é distribuída pelos releases de nexus-exchange-cli. Consulte SDKs e ferramentas para todos os 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.
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 para ver como cada interface faz isso e como as chaves de API se vinculam a uma rede, e APIs e limites para a URL base atual. A chave HMAC que essas rotas exigem fica restrita à rede em que foi criada.
Referência
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:
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.
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:
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:
um valor: calculado e autoritativo;
null: reportado, mas não calculável, e o<field>_errorcorrespondente diz por quê;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 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
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 e examples/portfolio.rs.
Relacionados
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/feesnão tem programa de níveis ou descontos por conta hoje, eleveragereportanullaté que o estado de margem de que ele precisa seja espelhado. Credenciais e saldos da testnet não têm valor no mundo real.
Atualizado