> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.6mm.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server. # 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](/pt-PT/sdk/agent-sdk/java/quick-start). ## 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. ```java 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: ```java 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: ```java 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: ```java 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`: ```java 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](/pt-PT/sdk/agent-sdk/java/perpetual-queries) 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 * [Fonte oficial v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Visão geral da consulta e paginação](/pt-PT/sdk/agent-sdk/java/perpetual-queries) * [Guia de atualização](/pt-PT/sdk/agent-sdk/java/upgrade) ## 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. |