On\Off-Ramp – Immediate Settlement via API & Dashboard

✅ Prerequisites

Before using the immediate on/off-ramp feature, ensure the following are configured in your Trace Finance environment:

A BRL account linked to your Trace entity
A crypto wallet registered with Trace Finance
At least one counterparty registered
At least one counterparty wallet (for on-ramp)
At least one client bank account (for off-ramp)
Only USDC and USDT are supported
Supported networks: Solana, Base, Polygon, Tron, Ethereum, BSC
Only BRL is supported as the fiat currency

🚀 How-To: Create Immediate On-Ramp and Off-Ramp Orders

You can initiate on/off-ramp orders via the API or the Dashboard.

Immediate Processing

To process an order immediately:

API: Include "immediate": true in the order payload
Dashboard: Check the box labeled “Process Immediately” during order creation

Required Settlement Target

When creating an order, the target bank channel must be defined:

On-ramp (BRL → Crypto): select a counterparty wallet
Off-ramp (Crypto → BRL): select a client bank account

In the Dashboard, destination accounts can be selected or registered through menus

🔁 Settlement Flow Overview

On-Ramp: BRL → Crypto

Trace debits BRL from the client's bank account
After confirmation, Trace triggers the on-chain transfer of the crypto asset (USDC/USDT) to the counterparty's wallet
Once both legs are confirmed, the settlement and order are marked as COMPLETED

Off-Ramp: Crypto → BRL

Trace debits the crypto amount from the client’s wallet
After on-chain confirmation, a BRL bank payment (PIX/TED) is issued to the client's bank account
When both legs are confirmed, the settlement and order are marked as COMPLETED

🧩 Sequence Diagrams

On-Ramp Flow (BRL → Crypto)

Off-Ramp Flow (Crypto → BRL)

⚠️ Key Validations

immediate = true requires a valid targetBankChannelId
On-Ramp: The target must be a CRYPTO_WALLET of a counterparty and support the selected crypto asset
Off-Ramp: The target must be a client bank account and support BRL

✅ Best Practices

Always use idempotentId to avoid duplicated orders
Persist and log the x-request-id for traceability
Monitor order and settlement statuses via webhooks

Updated 1 day ago