The single money-movement resource. The pair (source.type, destination.type) selects the flow - you never call a different endpoint for on-ramp vs off-ramp:

Sending to an on-chain address runs on this route. A wallet source with a crypto_address destination is a custody move: OZAV signs from the source wallet's vault and broadcasts. No quote is involved (it is a same-asset move, not an exchange), so send amount and omit quote_id. It needs the custody or the liquidity product. The /wallets routes need custody: listing wallets (GET /wallets), reading a customer's wallet, its deposit addresses, addresses and policy, and POST /wallets/{wallet_id}/transfers. It is subject to the two controls below.

On-ramp from the account balance. An account source spends the BRL balance of the customer's BRL named account: Pix payments to the account's key accumulate there, and nothing converts by itself. An account that cannot fund an order yet gets 422 ACCOUNT_NOT_READY: it is not active, its institution cannot send Pix, or its balance could not be read just now. Converting more than the balance not already committed to an open order gets 422 ACCOUNT_BALANCE_INSUFFICIENT. If OZAV pauses this flow, every organization gets 422 ACCOUNT_FUNDED_ORDERS_NOT_ENABLED at once: nothing in your request causes it.

Some of these refusals come after the transfer is recorded: it ends failed, and a retry with the same Idempotency-Key returns the same refusal. To try again later, send the request with a new key. An ACCOUNT_NOT_READY that persists across a few retries means the account cannot fund orders yet. Each conversion is one transfer with a quote, like any on-ramp, and the BRL 1,000 on-ramp floor applies per transfer, not per deposit. A smaller deposit stays in the account and adds up with the next ones.

In the sandbox, a test key converts from a sandbox account: credit it first with POST /accounts/{account_id}/simulate/credit, then send the transfer. The order runs on the simulator and the conversion debits the simulated balance.

Wallet-to-wallet runs here too. The source wallet must belong to the customer_id on the request - that is whose money moves. The destination only has to be a wallet in your organization, so you can move value between two of your customers' wallets. A wallet outside your organization is not found, and a deactivated wallet does not receive.

The two controls:

• Managed wallets only. A self-custody source is refused with 422 WALLET_NOT_MANAGED - OZAV holds no key to sign with. That send goes through POST /wallets/{wallet_id}/transaction-intents, which returns unsigned calldata for the end-user's own key.
• Travel Rule (BCB Resolution 520) on any send that leaves custody. A crypto_address destination without complete Travel Rule data is refused with 422 TRAVEL_RULE_REQUIRED, and details.missing_fields names each field that is missing. A destination that is an ozav_wal_ id is exempt: the move stays inside custody and both sides are already verified.

POST /wallets/{wallet_id}/transfers also carries a destination memo, which networks like Stellar need for exchange deposits (an exchange credits by memo). POST /transfers has no memo field, so a memo-bearing send belongs on the wallets surface even after custody lands here.

Receiving crypto needs nothing from you, and is not a transfer. Fund an address from GET /wallets/{wallet_id}/deposit-addresses and the credit lands on the wallet by itself. You see it in two places already:

• GET /wallets/{wallet_id}/balances reflects the new amount;
• GET /transactions lists the arrival alongside your transfers, in one timeline, so you do not have to stitch two listings together.

Creating a transfer with a crypto_payment source is refused with 422 NOT_AVAILABLE, and that refusal is permanent rather than pending: an arrival is observed, never requested, so there is nothing for you to create. The one thing still missing is a push notification for it - today you learn about an arrival by reading, not by being told.

BRL/Pix on-ramp returns transaction-specific Pix payment instructions on source.payment_instructions. BRL/Pix off-ramp creates the operation only after the customer's stable funds are reserved; final Pix-out remains gated until settlement rails are enabled. Other combinations fail closed (422 RAIL_NOT_AVAILABLE / NOT_AVAILABLE) until settlement is enabled - never a silent partial result. See x-ozav-transfer-flow-availability for the machine-readable status.

quote_id is required whenever source and target currencies differ, and is authoritative for the amount when present. For a same-currency move (no FX, so no quote) provide amount - it is how much to move. Exactly one of quote_id or amount must be present; supplying both is a 400. The Idempotency-Key header is required.

{
  "amount": {
    "amount": "1250.00"
  },
  "travel_rule": {
    "originator": {
      "identity_documents": [
        {
          "type": "cpf",
          "number": "11144477735",
          "issuing_country": "BR"
        }
      ],
      "address": {
        "country": "BR"
      }
    },
    "beneficiary": {
      "identity_documents": [
        {
          "type": "cpf",
          "number": "11144477735",
          "issuing_country": "BR"
        }
      ],
      "address": {
        "country": "BR"
      }
    }
  }
}