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

Leia data.limits (preferência da instituição + política do broker). Não envie teto no body.

{
  "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,
    "limits": {
      "buyMaxBrl": "300.00",
      "sellMaxBrl": "50000.00",
      "buySource": "FIRST_PURCHASE",
      "sellSource": "SELL_AUTO_APPROVE_CEILING",
      "buyReason": null,
      "sellReason": null,
      "firstPurchase": {
        "active": true,
        "limitBrl": "300.00",
        "enabled": true
      }
    },
    "createdAt": "2026-09-15T12:00:00.000Z"
  }
}

Campo	Descrição
`limits.buyMaxBrl`	Teto BUY aplicável neste destino (decimal BRL) ou `null`. Na 1ª compra cautelar é o cautelar (default `"300.00"`).
`limits.sellMaxBrl`	Teto SELL de auto-aprovação da IF (decimal BRL) ou `null`.
`limits.buySource`	`FIRST_PURCHASE`, `BUY_AUTO_APPROVE_CEILING` ou `BUY_AUTO_EXECUTE_CAP`. `null` se o BUY não resolveu.
`limits.sellSource`	`SELL_AUTO_APPROVE_CEILING`. `null` se o SELL não resolveu.
`limits.buyReason` / `limits.sellReason`	Só com teto `null`: `CEILING_DISABLED`, `CEILING_UNREADABLE` ou `POLICY_UNRESOLVED`. Não é ilimitado.
`limits.firstPurchase.active`	`true` no regime cautelar de 1ª compra (ainda não houve BUY `SETTLED` limpo nesta carteira+rede).
`limits.firstPurchase.enabled`	Toggle institucional da 1ª compra.
`limits.firstPurchase.limitBrl`	Teto cautelar em BRL quando `active` e `enabled`; senão `null`.

Os flags planos isFirstPurchase, firstPurchaseLimitBrl e firstPurchaseLimitEnabled continuam no payload (compatíveis com cotação/ordem). Prefira limits para o cap aplicável.

Teto null + reason não vira 503: a carteira segue 201. limits omitido = broker ainda sem o campo. limits: null = fail-closed do broker.

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. Cada item traz o mesmo limits do 201, resolvido na hora da leitura.

{
  "meta": {
    "total": 1
  },
  "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,
      "limits": {
        "buyMaxBrl": "300.00",
        "sellMaxBrl": "50000.00",
        "buySource": "FIRST_PURCHASE",
        "sellSource": "SELL_AUTO_APPROVE_CEILING",
        "buyReason": null,
        "sellReason": null,
        "firstPurchase": {
          "active": true,
          "limitBrl": "300.00",
          "enabled": true
        }
      },
      "createdAt": "2026-09-15T12:00:00.000Z"
    }
  ]
}

Depois do primeiro BUY SETTLED, releia o GET: firstPurchase.active passa a false, limitBrl a null e buyMaxBrl deixa o cautelar (buySource=BUY_AUTO_APPROVE_CEILING ou BUY_AUTO_EXECUTE_CAP). Não cacheie limits. Teto null + reason não é ilimitado e não responde 503.

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.

Registrar carteira​

201 — carteira registrada​

Listar carteiras​

Cotar​

201 — cotação​

Criar ordem​

201 — ordem criada​

Consultar ordem​

Listar ordens​

Registrar carteira

`201` — carteira registrada

Listar carteiras

Cotar

`201` — cotação

Criar ordem

`201` — ordem criada

Consultar ordem

Listar ordens