Notus API

Ramp Quickstart

FIAT on/off ramp operations

FIAT Ramp

FIAT Ramp allows your users to convert between fiat currencies (FIAT) and cryptocurrencies in a simple and secure way. This module provides a complete solution for:

  • Deposits (On-Ramp): Convert FIAT to cryptocurrencies (ACH, PIX, WIRE, SPEI)
  • Withdrawals (Off-Ramp): Convert cryptocurrencies to FIAT (ACH, PIX, WIRE, SPEI, ACH_COP, TRANSFERS)

Operation Types

On-Ramp (Deposit)

Converts fiat currency to cryptocurrencies:

  • Input: BRL, USD, MXN, etc.
  • Output: USDC, BRZ.
  • Destination: User's wallet

Off-Ramp (Withdrawal)

Converts cryptocurrencies to fiat currency:

  • Input: BRZ, USDC.
  • Output: BRL, USD, ARS, etc.
  • Destination: User's bank account

Important: Before executing off-ramp operations, always verify that the individual has sufficient crypto balance in their wallet to complete the transaction. Insufficient balance will cause the operation to fail.

Supported Currencies

Fiat Currencies

  • BRL - Brazilian Real
  • USD - US Dollar
  • MXN - Mexican Peso
  • COP - Colombian Peso
  • ARS - Argentine Peso

Cryptocurrencies

  • USDC - USD Coin
  • BRZ - Brazilian Digital Token

Supported Chains

  • POLYGON - Polygon Network
  • ARBITRUM - Arbitrum Network
  • BASE - Base Network

Token Compatibility by Chain

TokenPOLYGONARBITRUMBASE
USDC✅✅✅
BRZ✅❌❌

Monthly limit: $9,000 USD (after KYC approval)

Important: To trade BRZ, KYC must have been completed with a Brazilian document (RG, CNH, or Brazilian Passport).

Chain IDs

  • POLYGON: 137
  • ARBITRUM: 42161
  • BASE: 8453

Operation Flow

On-Ramp (Deposit)

1. Create Quote

First, you must get a quote for the deposit:

POST /fiat/deposit/quote

Request:

{
  "paymentMethodToSend": "PIX",
  "receiveCryptoCurrency": "USDC",
  "amountToSendInFiatCurrency": 80,
  "individualId": "ind_1234567890abcdef",
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "chainId": 137
}

Response:

{
  "depositQuote": {
    "quoteId": "c8bb5c9c-9a32-4c91-9d4a-6fdd86c9d3b6",
    "amountToSendInFiatCurrency": "80",
    "amountToReceiveInCryptoCurrency": "14.27944",
    "expiresAt": "2025-07-24T14:58:22.702Z"
  }
}

2. Create Order

After getting the quote, create the deposit order:

POST /fiat/deposit

Payload:

{
	"quoteId": "c8bb5c9c-9a32-4c91-9d4a-6fdd86c9d3b6"
}

Response:

{
	"depositOrder": {
		"orderId": "order_1234567890abcdef",
		"expiresAt": "2025-01-20T11:00:00.000Z",
		"paymentMethodToSendDetails": {
			"type": "PIX",
			"pixKey": "<pix_key>",
			"base64QrCode": "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"
		}
	}
}

On-Ramp (Deposit) Flow Diagram

Fiat Deposit Sequence Diagram

Off-Ramp (Withdrawal)

1. Create Quote

Get a quote for the withdrawal:

POST /fiat/withdraw/quote

Request:

{
  "individualId": "ind_1234567890abcdef",
  "amountToSendInCryptoCurrency": "10",
  "cryptoCurrencyToSend": "USDC",
  "paymentMethodToReceiveDetails": {
    "type": "PIX",
    "pixKey": "[email protected]"
  },
  "chainId": 137
}

Response:

{
	"withdrawQuote": {
		"quoteId": "1305c776-6d11-40e8-ade4-1d07bfaa95b9",
		"cryptoCurrencyToSend": "USDC",
		"fiatCurrencyToReceive": "BRL",
		"amountToSendInCryptoCurrency": "10",
		"estimatedGasFeeInCryptoCurrency": "0.01",
		"transactionFeeInCryptoCurrency": "0",
		"expiresAt": "2025-07-30T16:26:31.793Z",
		"amountToReceiveInFiatCurrency": "55.55"
	}
}

2. Create Order

Create the withdrawal order:

POST /fiat/withdraw

Request:

{
	"quoteId": "1305c776-6d11-40e8-ade4-1d07bfaa95b9",
	"walletAddress": "0x9ba7dbda009d6fdeb0aebf82c62f3cdc4a941091"
}

Response:

{
	"withdrawOrder": {
		"userOperationHash": "0x2d96e00c119ff08ed90b934800768602e8d99dd4de996900292ec2e2600114ee",
		"authorization": null,
		"orderId": "f64ea5a8-ee76-4dc7-b845-274843415025",
		"amountToSendInCryptoCurrency": "10",
		"amountToReceiveInFiatCurrency": "55.55",
		"transactionFeeAmountInCryptoCurrency": "0",
		"estimatedGasFeeAmountInCryptoCurrency": "0.01",
		"expiresAt": "2025-07-30T16:26:31.793Z"
	}
}

3. Execute User Operation

After receiving the order response, you must sign the userOperationHash and execute the User Operation:

POST /crypto/execute-user-op

Payload:

{
  "userOperationHash": "0x2d96e00c119ff08ed90b934800768602e8d99dd4de996900292ec2e2600114ee",
  "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Important: For Off-Ramp operations, it is mandatory to sign the userOperationHash and execute the User Operation for the transaction to be processed on the blockchain.

Off-Ramp (Withdrawal) Flow Diagram

Fiat Withdraw Sequence Diagram

Webhooks

Configure webhooks to receive real-time notifications about the status of your FIAT ramp operations.

Webhook Example - On-Ramp (Deposit)

{
  "chainId": 137,
  "event_type": "ramp.deposit",
  "orderId": "order_85b80496-f102-4585-8047-4394dab3b6a8",
  "receivedCryptoAmount": "0.05",
  "receivedCryptoCurrency": "ETH",
  "sendFiatAmount": "100.00",
  "sendFiatCurrency": "USD",
  "status": "COMPLETED",
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "type": "ON_RAMP",
  "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
}

Webhook Example - Off-Ramp (Withdrawal)

{
  "chainId": 137,
  "estimatedGasFeeAmount": "0.001",
  "event_type": "ramp.withdraw",
  "orderId": "order_85b80496-f102-4585-8047-4394dab3b6a8",
  "receivedFiatAmount": "100.00",
  "receivedFiatCurrency": "USD",
  "sendCryptoAmount": "0.05",
  "sendCryptoCurrency": "USDC",
  "status": "COMPLETED",
  "transactionFeeAmount": "0.002",
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "type": "OFF_RAMP",
  "userOpHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
}

Available webhooks: ramp.deposit and ramp.withdraw with status COMPLETED, FAILED, PROCESSING

Next Steps

Now that you know about FIAT Ramp, you can:

  • Implement deposits and withdrawals in your application
  • Configure webhooks for notifications
  • Customize the user experience
  • Monitor transactions via API

Important: Always verify that the user has approved KYC before starting FIAT ramp operations.

KYC Quickstart

Know Your Customer verification process

Overview

Next Page