Carteira de Financiamento

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

Pré-requisitos de exemplo

Os trechos Java compartilham essas importações. Inicialize client usando o Quick Start e obtenha platformUserId da ligação salva. Os exemplos de IDs de usuário/pedido devem ser substituídos por 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	usar
Carteira de usuário do próprio comerciante	Sistema de contabilidade próprio do comerciante	O saldo disponível do usuário no lado do comerciante
Financiamento da plataforma	`queryUserAssets` de `funding`	Fundos de negociação de segundos e transferência mútua de financiamento/contrato
Contrato de plataforma	O campo de ativo de contrato de `queryUserAssets`	Margem de contrato perpétuo e saldo transferível

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

Consulte as duas carteiras da plataforma de usuários 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 é usada por padrão.

campos de resposta	significado
`walletBalance`, `availableBalance`, `frozenMargin`, `usedMargin`, `isolatedMargin`	Valores relacionados à 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; solicitações antigas que omitem o ambiente não retornam 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, 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	Somente valor fixo
`FUNDING_TO_PARTNER`	Financiamento da plataforma → Comerciante	Somente 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 suporta apenas 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 registre-o como a resposta final amount; “todos” inclui apenas os fundos retiráveis.

Exemplo: O comerciante transfere 10 USDT para financiamento simulado. Primeiro salve a ordem comercial e o ambiente no sistema do comerciante e depois envie a solicitação:

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 usando o agentOrderNo original; diferentes operações e diferentes ambientes usam diferentes números de pedido. Será rejeitada alteração de quantidade, usuário, direção ou ambiente com o mesmo número de pedido. 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 retornadas orderNo, direction, currency, amount, resultCode, etc. code=0 significa apenas que a solicitação foi processada com sucesso e você precisa continuar a julgar status.

resultado	Processamento de comerciante
`SUCCESS`	Processamento contábil 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`	Liberar a reserva local de acordo com o resultado claro da falha; criar uma nova ordem de negócios quando o negócio precisar ser iniciado novamente

A consulta de financiamento usa 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 pode substituí-lo. Salve o ambiente original e passe-o explicitamente durante a recuperação. Se environment for omitido de wallet-transfer-status, o servidor utiliza o ambiente salvo no pedido original, incluindo pedidos simulados. Um ambiente explicitamente conflitante retorna 102002 (order environment mismatch). Quando o chamador omite o ambiente, a resposta omite environment também; isso não significa que o pedido original seja uma ordem de produção.

Os depósitos e saques locais dos comerciantes são idempotentes; pedidos 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 utiliza uma consulta dedicada para confirmar o status final; não presuma que a transferência de contrato antigo Webhook ou métodos de reversão sejam automaticamente aplicáveis ao Financiamento.

Fluxo de transferência de contrato existente

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

A resposta de financiamento original usa orderStatus; a resposta do Financiamento usa status, não os misture. A transferência original Webhook é verificada usando X-Agent-Timestamp, X-Agent-Nonce, X-Agent-Signature, e o texto da assinatura original é timestamp + nonce + rawBody; o corpo da solicitação original é primeiro verificado e depois desserializado e idempotente. Notificações explícitas de ambiente simulado contêm environment=SIMULATED, notificações de produção permanecem compatíveis com campos antigos. O valor, o número do pedido, o status e o ambiente precisam 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 pedido do parceiro globalmente exclusivo; persistir antes de enviar.
`agentUserId / platformUserId`	Um	Identifique o usuário vinculado; se ambos forem fornecidos, eles devem corresponder.
`direction`	Sim	Uma das quatro direções documentadas acima.
`currency`	Padrão USDT	Apenas USDT é suportado.
`transferAll`	Padrão falso	Somente 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 fundos simulados.

Campos de resposta de financiamento

Campo	Significado
`orderNo`	Identificador da operação retornada; guarde junto com o número original do pedido do parceiro.
`status`	SUCCESS / PROCESSING / FAILED; determina a conclusão do negócio.
`direction / currency`	Direção 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 usuário retornada; compare com o pedido salvo.
`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 status do pedido original.