Carteira de Financiamento

Este guia é dirigido a Agent Java SDK v0.3.0, Java 8+ e ao contrato público assinalado. Os exemplos são executados num back-end de parceiro após a inicialização de client em Início rápido.

Pré-requisitos de exemplo

Os trechos Java partilham estas importações. Inicialize client utilizando o Quick Start e obtenha platformUserId a partir da ligação guardada. Os exemplos de IDs de utilizador/encomenda devem ser substituídos pelos seus próprios valores persistentes.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

Consultas e transferências de carteira

Distinguir as três carteiras

carteira	Fonte de equilíbrio	uso
Carteira de utilizador do próprio comerciante	Sistema de contabilidade próprio do comerciante	O saldo disponível do utilizador no lado do comerciante
Financiamento da plataforma	`queryUserAssets` de `funding`	Segundos fundos de negociação e transferência mútua de financiamento/contrato
Contrato de plataforma	O campo de ativos do contrato de `queryUserAssets`	Margem de contrato perpétuo e saldo transferível

queryAccount Consulte a conta de margem da plataforma do comerciante, e não a carteira do utilizador do comerciante. Esta interface não possui parâmetros environment e não pode ser consultada como um ativo de utilizador simulado.

Consulte as duas carteiras da plataforma de utilizadores simulados:

QueryUserAssetsResponse assets = client.queryUserAssets(
        QueryUserAssetsRequest.of(platformUserId)
                .withFunding()
                .withEnvironment(ExecutionEnvironment.SIMULATED));

Interface: POST /v1/agent/query-user-assets. O financiamento é solicitado apenas quando includeFunding=true; a semântica de consulta do ativo do contrato original é utilizada por defeito.

campos de resposta	significado
`walletBalance`, `availableBalance`, `frozenMargin`, `usedMargin`, `isolatedMargin`	Valores relacionados com a carteira de contrato
`funding.assetCode`	Atualmente USDT
`funding.availableAmount`, `heldAmount`, `totalAmount`	Financiamento disponível, ocupado e valor total
`funding.materialized`	Se a conta de financiamento foi materializada?
`environment`	Este campo é repetido quando o ambiente é passado explicitamente; pedidos antigos que omitem o ambiente não devolvem este campo.
`isSimulatedUser`	Classificação de contas; não pode substituir a seleção do ambiente de negociação

Os valores são tratados como strings ou BigDecimal, e não float/double.

Instruções de transferência de financiamento

Criar: POST /v1/agent/wallet-transfer, SDK walletTransfer.

`direction`	Fluxo de fundos	`transferAll`
`PARTNER_TO_FUNDING`	Comerciante → Financiamento da plataforma	Apenas valor fixo
`FUNDING_TO_PARTNER`	Financiamento da plataforma → Comerciante	Apenas valor fixo
`FUNDING_TO_CONTRACT`	Mesma plataforma ambiental Financiamento → Contrato	Suporta valor fixo ou todos os fundos retiráveis
`CONTRACT_TO_FUNDING`	Contrato da mesma plataforma ambiental → Financiamento	Suporta valor fixo ou todos os fundos retiráveis

A moeda atual apenas suporta USDT. O valor fixo deve ser uma string positiva com até 8 casas decimais e não pode utilizar notação científica. Quando transferAll=true, omita amount e registe-o como resposta final amount; “todos” inclui apenas os fundos retiráveis.

Exemplo: O comerciante transfere 10 USDT para financiamento simulado. Primeiro guarde a ordem comercial e o ambiente no sistema do comerciante e depois envie o pedido:

String fundingOrderNo = "SIM-FUNDING-20261010-000001";
WalletTransferResponse transfer = client.walletTransfer(
        WalletTransferRequest.of(fundingOrderNo, "merchant-user-001",
                "PARTNER_TO_FUNDING", "10.00000000", false)
                .withEnvironment(ExecutionEnvironment.SIMULATED));

Financiamento Transferir todos os recursos que podem ser transferidos para o Contrato simulado:

WalletTransferResponse move = client.walletTransfer(
        WalletTransferRequest.of("SIM-F2C-20261010-000001", "merchant-user-001",
                "FUNDING_TO_CONTRACT", null, true)
                .withEnvironment(ExecutionEnvironment.SIMULATED));

A mesma operação deve continuar utilizando o agentOrderNo original; diferentes operações e diferentes ambientes utilizam diferentes números de encomenda. Será rejeitada a alteração de quantidade, utilizador, direção ou ambiente com o mesmo número de encomenda. As transferências de financiamento/contrato só podem ser realizadas dentro do mesmo ambiente, e os fundos simulados não podem ser transferidos para fundos reais.

Confirmação de resultado e recuperação de resultado desconhecido

As respostas de financiamento são representadas por status, SUCCESS, PROCESSING, ou FAILED, e são devolvidas orderNo, direction, currency, amount, resultCode, etc. code=0 significa apenas que o pedido foi processado com sucesso e precisa de continuar a julgar status.

resultado	Processamento de comerciante
`SUCCESS`	Processamento contabilístico local completo com base no valor real
`PROCESSING`	Mantenha-o local para confirmação e verifique o pedido original
HTTP Tempo limite, erro de rede, resultado não pode ser analisado	O resultado é considerado desconhecido e a ordem original é consultada; não pode ser diretamente determinado como uma falha ou criar um novo pedido e tentar novamente.
Identificado `FAILED`	Libertar a reserva local de acordo com o resultado claro da avaria; criar uma nova ordem de trabalhos quando o negócio necessitar de ser iniciado novamente

A consulta de financiamento utiliza a interface dedicada POST /v1/agent/wallet-transfer-status:

WalletTransferResponse recovered = client.queryWalletTransfer(
        WalletTransferQueryRequest.of(fundingOrderNo)
                .withEnvironment(ExecutionEnvironment.SIMULATED));

Utilize este endpoint dedicado para recuperar a operação de financiamento original; queryOrder não o pode substituir. Guarde o ambiente original e passe-o explicitamente durante a recuperação. Se environment for omitido de wallet-transfer-status, o servidor utiliza o ambiente guardado no pedido original, incluindo os pedidos simulados. Um ambiente explicitamente conflituante devolve 102002 (order environment mismatch). Quando o chamador omite o ambiente, a resposta omite também environment; isto não significa que o pedido original seja uma ordem de produção.

Os depósitos e levantamentos locais dos comerciantes são idempotentes; encomendas e saldos persistentes são reservados antes do início e são reservados para confirmação quando o resultado é desconhecido. O acesso ao financiamento recorre a uma consulta dedicada para confirmar o estado final; não presuma que a transferência de um contrato antigo Webhook ou os métodos de reversão são automaticamente aplicáveis ao Financiamento.

Fluxo de transferência de contrato existente

Os transfer, transferAllOut, reverse, queryOrder, listOrders continuam a processar o processo de transferência do contrato original. queryOrder está a consultar ordens de transferência de fundos, listOrders é uma lista de reconciliação de transferências; em vez de, Consultas perpétuas são utilizados para ordens de negociação perpétuas.

A resposta de financiamento original utiliza orderStatus; a resposta do Financiamento utiliza status, não os misture. A transferência original Webhook é verificada através de X-Agent-Timestamp, X-Agent-Nonce, X-Agent-Signature, e o texto da assinatura original é timestamp + nonce + rawBody; o corpo do pedido original é primeiro verificado e depois desserializado e idempotente. As notificações explícitas de ambiente simulado contêm environment=SIMULATED, as notificações de produção permanecem compatíveis com os campos antigos. O valor, o número do pedido, o estado e o ambiente precisam de ser verificados com a ordem comercial local.

Fonte e guias relacionados

Campos de solicitação de financiamento

Campo	Obrigatório	Significado
`agentOrderNo`	Sim	Número de encomenda do parceiro globalmente exclusivo; persistir antes de enviar.
`agentUserId / platformUserId`	Um	Identifique o utilizador vinculado; se ambos forem fornecidos, deverão corresponder.
`direction`	Sim	Uma das quatro direções acima documentadas.
`currency`	Padrão USDT	Apenas USDT é suportado.
`transferAll`	Padrão falso	Apenas as transferências internas de financiamento/contrato suportam true.
`amount`	Condicional	Sequência decimal positiva para uma transferência fixa; omitir para transferAll=true.
`environment`	Opcional	Produção quando omitida para nova transferência; SIMULATED seleciona os fundos simulados.

Campos de resposta ao financiamento

Campo	Significado
`orderNo`	Identificador da operação devolvida; guarde junto com o número original da encomenda do parceiro.
`status`	SUCCESS / PROCESSING / FAILED; determina a conclusão do negócio.
`direction / currency`	Sentido de transferência e ativo confirmados.
`amount`	Valor real transferido como uma string.
`transferAll`	Se esta operação solicitou todos os fundos retiráveis.
`agentUserId / platformUserId`	Identidade do utilizador devolvida; compare com o pedido guardado.
`resultCode`	Detalhe do resultado da operação; reter para reconciliação e apoio.
`environment`	Ecoado quando o chamador o forneceu explicitamente; a ausência não é prova de produção para uma consulta de estado do pedido original.