# Carteiras e conversão

Cada moeda tem a sua própria carteira, com saldo separado: `BRL` (saldo principal), `USDT`, `MXN`, `COP` e `CLP`. Você recebe direto na moeda, converte de uma carteira para outra sem sacar e saca quando quiser.

| Ação | Como | Onde cai |
| --- | --- | --- |
| Receber | `POST /charges` (Pix em BRL) ou `POST /fx/charges` (USDT, MXN, COP, CLP) | Na carteira da moeda cobrada |
| Converter | `POST /conversions` | Sai da carteira de origem e entra na de destino. Nada é sacado. |
| Sacar | `POST /withdrawals` (Pix) ou `POST /fx/withdrawals` | Sai da carteira para fora da StacePay |

> ✅ Valores sempre em unidade mínima da moeda: centavos para BRL, MXN e COP; peso inteiro para CLP; micro (6 casas) para USDT. Toda resposta traz os campos `decimals`.

## Saldos

`GET /wallets`

Lista todas as carteiras disponíveis para a sua conta, inclusive BRL. `reserved` é o valor separado para saques em andamento.

_json_

```json
{
  "object": "list",
  "data": [
    { "object": "wallet", "currency": "BRL", "decimals": 2, "available": 1250000, "reserved": 0, "convertible": true },
    { "object": "wallet", "currency": "USDT", "decimals": 6, "available": 184120000, "reserved": 0, "convertible": true }
  ]
}
```

## Cotação

Mostra quanto entra na carteira de destino, já descontadas as taxas. Não debita nada.

`POST /conversions/quote`

| Campo | Tipo |  | Descrição |
| --- | --- | --- | --- |
| `from_currency` | string | obrigatório | Carteira de origem: BRL, USDT, MXN, COP ou CLP. |
| `to_currency` | string | obrigatório | Carteira de destino, diferente da origem. |
| `amount` | integer | obrigatório | Valor a converter, em unidade mínima da moeda de origem. |

_curl_

```bash
curl -X POST https://stacepay.com.br/api/v1/conversions/quote \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from_currency": "BRL", "to_currency": "USDT", "amount": 100000}'
```

_json_

```json
{
  "object": "conversion_quote",
  "from_currency": "BRL",
  "to_currency": "USDT",
  "amount": 100000,
  "fee_amount": 500,
  "estimated_amount": 184120000,
  "rate": 0.18504,
  "from_decimals": 2,
  "to_decimals": 6
}
```

> ⚠️ A conversão usa a cotação do momento em que é executada, que pode variar um pouco em relação à prévia.

## Converter

`POST /conversions`

> ✅ Use um `Idempotency-Key`. KYC aprovado é obrigatório. Os campos são os mesmos da cotação.

_curl_

```bash
curl -X POST https://stacepay.com.br/api/v1/conversions \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Idempotency-Key: conv-0001" \
  -H "Content-Type: application/json" \
  -d '{"from_currency": "BRL", "to_currency": "USDT", "amount": 100000}'
```

_json_

```json
{
  "object": "conversion",
  "id": "cv_3f9a1c2b7d4e5f60",
  "status": "completed",
  "from_currency": "BRL",
  "to_currency": "USDT",
  "from_decimals": 2,
  "to_decimals": 6,
  "amount": 100000,
  "fee_amount": 500,
  "converted_amount": 184110000,
  "rate": 0.18503,
  "failure_reason": null,
  "completed_at": "2026-11-10T15:20:02-03:00",
  "created_at": "2026-11-10T15:20:00-03:00"
}
```

O valor de `amount` sai da carteira de origem na hora. Com `completed`, `converted_amount` já está na carteira de destino.

## Listar e buscar

`GET /conversions?limit=20&offset=0`

`GET /conversions/{id}`

## Status possíveis

| Status | Significado |
| --- | --- |
| `processing` | Origem debitada, aguardando a confirmação da troca. |
| `completed` | Convertido. `converted_amount` entrou na carteira de destino. |
| `failed` | Recusada; o valor volta inteiro para a carteira de origem. Motivo em `failure_reason`. |

## Webhooks

| Evento | Quando |
| --- | --- |
| `conversion.completed` | A conversão foi concluída e o destino creditado. |
| `conversion.failed` | A conversão foi recusada e a origem devolvida. |

## Receber e sacar USDT

A carteira USDT funciona na rede Tron (TRC20).

- **Receber:** `POST /fx/charges` com `"currency": "USDT"`. A resposta traz o endereço de depósito e o valor exato a enviar (com casas decimais que identificam o pagamento). Veja [Moedas](https://stacepay.com.br/docs/moedas).
- **Sacar:** `POST /fx/withdrawals` com `"currency": "USDT"` e `"destination": {"address": "T..."}`.
