> 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.

# Utilizadores e ativos

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.*;
```

## Regras de ID do utilizador

`platformUserId` é o ID do utilizador externo 6MM. Atualmente é um número de 10 dígitos
cadeia de caracteres, por exemplo:

```text
1188041528
```

Regras:

* Armazene-o como uma string, e não como um número inteiro.
* Não gere, descodifique ou infira significado a partir dele.
* Utilize o seu próprio ID de utilizador do parceiro como `agentUserId`.
* Persista a relação entre `agentUserId`, `platformUserId` e `agentOrderNo`.

## Vincular utilizador

O Bind cria ou procura a relação entre um utilizador parceiro e um 6MM
utilizador da plataforma. Chame-o quando um utilizador entrar pela primeira vez no fluxo de negociação ou antes do
primeira transferência para 6MM.

```java
import com.sixmm.agent.model.BindRequest;
import com.sixmm.agent.model.BindResponse;

BindResponse resp = client.bind(
        BindRequest.of("agent-user-001")
                .withUsername("alice")
                .withExt("{\"source\":\"web\"}"));

System.out.println(resp.platformUserId);
System.out.println(resp.bindStatus);
System.out.println(resp.isSimulatedUser);
```

Campos de solicitação:

| Campo         | Tipo   | Obrigatório | Descrição                                                                           |
| ------------- | ------ | ----------- | ----------------------------------------------------------------------------------- |
| `agentUserId` | string | Sim         | ID de utilizador exclusivo do parceiro                                              |
| `username`    | string | Não         | Nome de visualização do parceiro utilizado como apelido do utilizador da plataforma |
| `ext`         | string | Não         | Campo de extensão. A string JSON é recomendada                                      |

Campos de resposta:

| Campo             | Tipo    | Descrição                          |
| ----------------- | ------- | ---------------------------------- |
| `platformUserId`  | string  | 6MM ID de utilizador externo       |
| `bindStatus`      | string  | Geralmente `BOUND`                 |
| `isSimulatedUser` | boolean | Se este for um utilizador simulado |

## Consultar conta do parceiro

```java
import com.sixmm.agent.model.QueryAccountRequest;
import com.sixmm.agent.model.QueryAccountResponse;

QueryAccountResponse resp = client.queryAccount(QueryAccountRequest.of("USDT"));

System.out.println(resp.agentCode);
System.out.println(resp.agentStatus);
resp.assets.forEach(asset -> {
    System.out.println(asset.currency);
    System.out.println(asset.depositBalance);
});
```

Quando `currency` está ausente, o SDK utiliza `defaultCurrency`.

## Consultar ativos do utilizador

```java
import com.sixmm.agent.model.QueryUserAssetsRequest;
import com.sixmm.agent.model.QueryUserAssetsResponse;

QueryUserAssetsResponse resp = client.queryUserAssets(
        QueryUserAssetsRequest.of("1188041528"));

System.out.println(resp.walletBalance);
System.out.println(resp.availableBalance);
System.out.println(resp.version);
```

Campos:

| Campo              | Tipo    | Descrição                          |
| ------------------ | ------- | ---------------------------------- |
| `walletBalance`    | string  | Saldo da carteira                  |
| `frozenMargin`     | string  | Margem congelada                   |
| `usedMargin`       | string  | Margem usada                       |
| `availableBalance` | string  | Saldo disponível                   |
| `isolatedMargin`   | string  | Margem isolada                     |
| `version`          | int64   | Versão do ativo                    |
| `isSimulatedUser`  | boolean | Se este for um utilizador simulado |

### 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`.

## 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)
* [Carteira de financiamento](/pt-PT/sdk/agent-sdk/java/funding-wallet)
* [Guia de atualização](/pt-PT/sdk/agent-sdk/java/upgrade)