Ramp (On/Off Ramp)

The ramp system allows you to convert between fiat currency (Brazilian Real - BRL) and cryptocurrencies. You can deposit BRL via PIX to receive cryptocurrencies, or withdraw cryptocurrencies to receive BRL via PIX. This guide covers both deposit and withdrawal processes.

Overview

The ramp system provides two main operations:

  • Deposit (On-Ramp) - Convert BRL (PIX) to cryptocurrencies
  • Withdraw (Off-Ramp) - Convert cryptocurrencies (BRZ) to BRL (PIX)

Both operations require:

  • Completed KYC verification
  • Created wallet
  • For withdrawals: Sufficient balance and a PIX beneficiary

Prerequisites

Before using ramp operations, ensure you have:

  • Completed authentication and have a valid access token
  • Completed KYC verification (status must be COMPLETED)
  • Created a wallet
  • For withdrawals: Created a PIX beneficiary (offchain beneficiary)

Deposit (On-Ramp)

Convert BRL to cryptocurrencies by depositing via PIX. The system will provide you with a PIX payment code and quote information.

Create deposit order

curl -X POST https://api.example.com/api/ramp/on \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amount": 100.00,
    "currency": "BRL",
    "tokenReceive": "USDC",
    "chainId": 137
  }'

Required Fields:

  • amount - Amount in BRL to deposit (must be greater than 0)
  • currency - Fiat currency (currently only "BRL" is supported)
  • tokenReceive - Token symbol you want to receive (e.g., "USDC", "ETH", "BRZ")
  • chainId - Chain ID where you want to receive the tokens (e.g., 137 for Polygon)

Response:

{
  "status": 200,
  "message": "Deposit order created successfully",
  "data": {
    "depositOrder": {
      "quoteId": "quote-id-123",
      "amount": 100.0,
      "paymentMethodToSend": "PIX",
      "amountToSendInFiatCurrency": 100.0,
      "receiveCryptoCurrency": "USDC",
      "chainId": 137,
      "walletAddress": "0x1234...",
      "pixCode": "00020126360014BR.GOV.BCB.PIX0114+5511999999999...",
      "expiresAt": "2024-01-01T01:00:00.000Z"
    }
  }
}

Response Fields:

  • depositOrder - Deposit order details
    • quoteId - Unique quote identifier
    • amount - Amount in BRL
    • paymentMethodToSend - Payment method (always "PIX")
    • amountToSendInFiatCurrency - Amount to send via PIX
    • receiveCryptoCurrency - Token you'll receive
    • chainId - Chain where tokens will be received
    • walletAddress - Your wallet address that will receive tokens
    • pixCode - PIX payment code (QR code or copy-paste code)
    • expiresAt - Quote expiration time

Important: The quote expires after a certain time. Make sure to complete the PIX payment before expiration.

Withdraw (Off-Ramp)

Convert cryptocurrencies (BRZ) to BRL by withdrawing to a PIX beneficiary. The system will process the withdrawal and send BRL to your PIX key.

Create withdraw order

curl -X POST https://api.example.com/api/ramp/off \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amount": "1.0",
    "beneficiaryId": "beneficiary-id"
  }'

Required Fields:

  • amount - Amount in BRZ to withdraw (humanized format, e.g., "1.0" for 1 BRZ)
  • beneficiaryId - ID of your PIX beneficiary (offchain beneficiary)

Response:

{
  "status": 200,
  "message": "Withdraw created successfully"
}

Note: The withdrawal is processed automatically. The transaction is signed and executed. BRL will be sent to your PIX beneficiary.

Supported Currencies

Fiat Currency

  • BRL - Brazilian Real (only supported fiat currency)

Cryptocurrencies (Deposit)

You can receive various cryptocurrencies when depositing:

  • USDC
  • ETH
  • BRZ
  • And other supported tokens

Check available tokens for the specific chain you're using.

Cryptocurrencies (Withdraw)

  • BRZ - Brazilian Real Token (only supported for withdrawals)
  • Must be on Polygon (chain ID 137)

Supported Chains

Deposit

Deposits can receive tokens on various EVM-compatible chains:

  • Polygon: 137
  • Ethereum Mainnet: 1
  • BSC: 56
  • And other supported chains

Withdraw

Withdrawals are only supported on:

  • Polygon: 137 (chain ID is fixed for withdrawals)

Deposit Flow

  1. Create Deposit Order - Call the deposit endpoint with amount and token details
  2. Receive PIX Code - Get the PIX payment code from the response
  3. Pay via PIX - Use the PIX code to make payment (QR code or copy-paste)
  4. Receive Tokens - Tokens are automatically sent to your wallet after payment confirmation

Important:

  • Quotes expire after a certain time
  • Payment must be completed before quote expiration
  • Tokens are sent automatically after payment is confirmed

Withdraw Flow

  1. Create PIX Beneficiary - Create an offchain beneficiary with your PIX key
  2. Check Balance - Ensure you have sufficient BRZ balance on Polygon
  3. Create Withdraw Order - Call the withdraw endpoint with amount and beneficiary ID
  4. Automatic Processing - The system automatically:
    • Validates your balance
    • Gets a withdrawal quote
    • Creates the withdrawal order
    • Signs and executes the transaction
    • Sends BRL to your PIX key

Important:

  • Withdrawals are processed automatically
  • Transaction is signed automatically
  • BRL is sent to your PIX beneficiary
  • Processing time varies based on network conditions

Amount Format

Deposit Amount

  • Format: Decimal number (e.g., 100.00)
  • Currency: BRL
  • Minimum: Must be greater than 0

Withdraw Amount

  • Format: String in humanized format (e.g., "1.0" for 1 BRZ)
  • Token: BRZ (18 decimals)
  • Example: 1 BRZ = "1.0"

Fees

Deposit Fees

Deposit fees are included in the quote. The quote shows:

  • Amount to send (BRL)
  • Amount to receive (crypto)
  • Exchange rate
  • Any applicable fees

Withdraw Fees

Withdrawal fees are deducted from the amount:

  • Transaction fee percentage is applied
  • Fee is deducted from the withdrawal amount
  • Final BRL amount received = withdrawal amount minus fees

Error Handling

KYC Not Completed

{
  "status": 400,
  "message": "Client KYC not completed"
}

This error occurs when your KYC status is not COMPLETED. Complete KYC verification before using ramp operations.

Wallet Not Found

{
  "status": 404,
  "message": "Wallet not found"
}

This error occurs when you haven't created a wallet yet.

Invalid Currency

{
  "status": 400,
  "message": "Only BRL is supported"
}

This error occurs when trying to deposit with a currency other than BRL.

Invalid Amount

{
  "status": 400,
  "message": "Amount is required"
}

This error occurs when the amount is missing or less than or equal to 0.

Fiat Beneficiary Not Found

{
  "status": 404,
  "message": "Fiat beneficiary not found"
}

This error occurs when the beneficiary ID doesn't exist or is not a PIX beneficiary.

Insufficient Balance

{
  "status": 400,
  "message": "Insufficient balance for transfer"
}

This error occurs when you don't have enough BRZ balance for the withdrawal.

Error Getting Quote ID

{
  "status": 500,
  "message": "Error getting quote id"
}

This error occurs when there's an issue getting a deposit quote.

Error Getting Order ID

{
  "status": 500,
  "message": "Error getting order id"
}

This error occurs when there's an issue getting a withdrawal quote.

Error Getting User Operation Hash

{
  "status": 500,
  "message": "Error getting user operation hash"
}

This error occurs when there's an issue creating the withdrawal transaction.

Complete Flow Examples

Deposit Example

# 1. Ensure KYC is completed
curl -X GET https://api.example.com/api/kyc/status \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 2. Ensure wallet is created
curl -X POST https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Create deposit order
curl -X POST https://api.example.com/api/ramp/on \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amount": 100.00,
    "currency": "BRL",
    "tokenReceive": "USDC",
    "chainId": 137
  }'

# 4. Pay via PIX using the pixCode from step 3
# 5. Tokens are automatically sent to your wallet

Withdraw Example

# 1. Create PIX beneficiary
curl -X POST https://api.example.com/api/beneficiary/offchain \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "pixType": "EMAIL",
    "pixKey": "user@example.com",
    "name": "My PIX Account"
  }'

# 2. Check your BRZ balance
curl -X GET https://api.example.com/api/wallet/portfolio \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Create withdraw order
curl -X POST https://api.example.com/api/ramp/off \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amount": "1.0",
    "beneficiaryId": "beneficiary-id-from-step-1"
  }'

# 4. BRL is automatically sent to your PIX key

Important Notes

  1. KYC Required: Both deposit and withdrawal operations require completed KYC verification. Your KYC status must be COMPLETED with a valid individual_id.

  2. Wallet Required: You must have created a wallet before using ramp operations. The wallet address is used to receive tokens (deposit) or send tokens (withdraw).

  3. PIX Only: Currently, only PIX payments are supported for both deposits and withdrawals.

  4. Quote Expiration: Deposit quotes expire after a certain time. Make sure to complete the PIX payment before expiration.

  5. Automatic Processing:

    • Deposits: Tokens are automatically sent after PIX payment confirmation
    • Withdrawals: Transactions are automatically signed and executed

  6. Withdraw Token: Only BRZ token can be withdrawn. Withdrawals are only supported on Polygon (chain ID 137).

  7. Beneficiary Required: For withdrawals, you must create a PIX beneficiary (offchain beneficiary) first.

  8. Balance Validation: The system validates your BRZ balance before processing withdrawals. Ensure you have sufficient balance.

  9. Transaction Fees: Withdrawal fees are deducted from the withdrawal amount. Check the fee structure before withdrawing.

  10. Exchange Rates: Exchange rates are provided in the quote. Rates may vary based on market conditions.

  11. Processing Time:

    • Deposits: Tokens are sent after PIX payment confirmation (usually within minutes)
    • Withdrawals: BRL is sent after transaction confirmation (varies based on network)

  12. Amount Format:

    • Deposit amounts are in decimal BRL format
    • Withdraw amounts are in humanized format (decimal string, e.g., "1.0" for 1 BRZ)

  13. PIX Code: The deposit PIX code can be used as a QR code or copy-paste code. Use it to make the payment through your banking app.

  14. Security: All transactions are processed securely. Withdrawals are automatically signed using your wallet's signing mechanism.

Security Considerations

  1. Verify PIX Code: Always verify the PIX code before making payment. Ensure the amount matches your deposit order.

  2. Check Beneficiary: Verify your PIX beneficiary details before withdrawing to ensure funds go to the correct account.

  3. Monitor Transactions: Keep track of your deposit and withdrawal transactions to ensure they complete successfully.

  4. Quote Expiration: Complete PIX payments before quote expiration to avoid issues.

  5. Balance Management: Maintain sufficient balance for withdrawals, accounting for fees.

  6. KYC Status: Ensure your KYC remains completed and valid for continued ramp access.

Was this page helpful?