Carteiras, cotações e ordens

Scope: crypto-caas.write para criar carteira, cotação e ordem; crypto-caas.read para listar carteiras e consultar/listar ordens.

Não envie accountId, assetNetworkId, ownerType, ownerDocument nem ownerName. A conta vem da credencial (BaaS usa x-account-id).

Registrar carteira

Endpoint: POST /crypto-caas/wallets

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/wallets' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: wallet-eth-001' \
  --data '{
    "network": "ETH",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "alias": "Destino USDT"
  }'

Credencial BaaS inclui --header 'x-account-id: <id_interno_da_conta>'.

Campo	Obrigatório	Descrição
network	Sim	BTC, ETH ou TRX. USDT, USDC e qualquer outro valor respondem 422.
address	Sim	Endereço na rede (10–255 caracteres).
alias	Não	Apelido (1–100 caracteres). Não volta no webhook crypto.wallet.registered.

201 — carteira registrada

A resposta vem em { data }. O id é um inteiro positivo em string. Use esse id como destinationWalletId (BUY) ou originWalletId (SELL).

{
  "data": {
    "id": "88",
    "network": "ETH",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "alias": "Destino USDT",
    "verificationStatus": "PENDING_VERIFICATION",
    "verificationMethod": null,
    "verifiedAt": null,
    "isActive": true,
    "eligibleForSellOrigin": false,
    "isFirstPurchase": true,
    "firstPurchaseLimitBrl": "300.00",
    "firstPurchaseLimitEnabled": true,
    "createdAt": "2026-09-15T12:00:00.000Z"
  }
}

Dispara crypto.wallet.registered se houver webhook CRYPTO ativo.

Listar carteiras

Endpoint: GET /crypto-caas/wallets

Scope: crypto-caas.read

Query	Obrigatório	Descrição
network	Não	BTC, ETH ou TRX.

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/wallets?network=ETH' \
  --header 'Authorization: Bearer <access_token>'

Resposta { meta: { total }, data }. Sem page/limit neste recurso.

SELL só usa carteira com eligibleForSellOrigin = true (ativa, VERIFIED na mesma rede, método elegível). Destino auto-verificado de BUY (DESTINATION_AUTO) não serve como origem.

Cotar

Endpoint: POST /crypto-caas/quotes

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/quotes' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quote-usdt-001' \
  --data '{
    "operation": "BUY",
    "network": "ETH",
    "asset": "USDT",
    "amountBrl": "100.00",
    "destinationWalletId": "88"
  }'

SELL:

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/quotes' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "operation": "SELL",
    "network": "ETH",
    "asset": "USDT",
    "amountBrl": "100.00",
    "originWalletId": "88"
  }'

Campo	Obrigatório	Descrição
operation	Sim	BUY ou SELL.
network	Sim	BTC, ETH ou TRX.
asset	Sim	BTC, ETH, USDT ou USDC, no par suportado da rede.
amountBrl	Não	Decimal positivo em string (ex.: "100.00").
destinationWalletId	Não	Id da carteira destino (inteiro positivo em string).
originWalletId	SELL: sim	Id da carteira origem. Ausente em SELL → 400.

201 — cotação

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "network": "ETH",
    "asset": "USDT",
    "operation": "BUY",
    "bidPriceBrl": "5.40",
    "askPriceBrl": "5.50",
    "midPriceBrl": "5.45",
    "networkFeeBrl": "2.50",
    "spreadBps": 30,
    "validUntil": "2026-09-15T12:01:00.000Z",
    "isFirstPurchase": true,
    "firstPurchaseLimitBrl": "300.00",
    "firstPurchaseLimitEnabled": true
  }
}

Use data.id como quoteId. A cotação expira em validUntil e pertence à mesma conta; cotação de outra conta não cria ordem.

Criar ordem

Endpoint: POST /crypto-caas/orders

Informe apenas um entre amountBrl e amountAsset. Pelo menos um é obrigatório.

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/orders' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-buy-001' \
  --data '{
    "operation": "BUY",
    "quoteId": "11111111-1111-4111-8111-111111111111",
    "amountBrl": "100.00",
    "destinationWalletId": "88",
    "firstPurchaseAcknowledgment": {
      "accepted": true,
      "textVersion": "v1"
    }
  }'

SELL:

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/orders' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "operation": "SELL",
    "quoteId": "11111111-1111-4111-8111-111111111111",
    "amountAsset": "0.010000000000000000",
    "originWalletId": "88"
  }'

Campo	Obrigatório	Descrição
operation	Sim	BUY ou SELL.
quoteId	Sim	UUID da cotação.
amountBrl ou amountAsset	Sim, só um	Decimal positivo em string. Os dois juntos → 400. Nenhum → 400.
destinationWalletId	BUY: sim	Carteira destino.
originWalletId	SELL: sim	Carteira origem elegível.
firstPurchaseAcknowledgment	Não	{ accepted: true, textVersion }. Envie quando isFirstPurchase for true.

201 — ordem criada

O id da ordem é UUID.

{
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "operation": "BUY",
    "network": "ETH",
    "asset": "USDT",
    "amountBrl": "100.00",
    "amountAsset": "18.180000",
    "lockedPriceBrl": "5.50",
    "networkFeeBrl": "2.50",
    "status": "PENDING_OPERATOR",
    "quoteId": "11111111-1111-4111-8111-111111111111",
    "destinationWalletId": "88",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "originWalletId": null,
    "originAddress": null,
    "depositAddress": null,
    "txHash": null,
    "txExplorerUrl": null,
    "createdAt": "2026-09-15T12:00:10.000Z",
    "updatedAt": "2026-09-15T12:00:10.000Z"
  }
}

Atestação de parceiro recusada responde 403. Ordem criada dispara crypto.order.updated nas transições de status.

Consultar ordem

Endpoint: GET /crypto-caas/orders/{id}

Scope: crypto-caas.read

O id é UUID. Ordem de outra conta responde 404.

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/orders/22222222-2222-4222-8222-222222222222' \
  --header 'Authorization: Bearer <access_token>'

A resposta é o mesmo { data } do 201, com o status corrente (txHash / txExplorerUrl quando a execução on-chain for pública).

Listar ordens

Endpoint: GET /crypto-caas/orders

Scope: crypto-caas.read

Query	Obrigatório	Descrição
status	Não	Um dos status da ordem.
operation	Não	BUY ou SELL.
page	Não	Padrão 1. Máximo 10000.
limit	Não	Padrão 20. Máximo 100.

curl --location 'https://secureapi.onz.finance/api/v2/crypto-caas/orders?operation=BUY&page=1&limit=20' \
  --header 'Authorization: Bearer <access_token>'

Resposta { meta: { total, page, limit }, data }.

Status possíveis: DRAFT, PENDING_POLICY_REVIEW, PENDING_OPERATOR, APPROVED, EXECUTING_MANUAL, EXECUTED, SETTLED, REJECTED, FAILED, EXPIRED, CANCELLED.