Core Concepts

Understand the fundamental concepts of customers, bank accounts, transactions, and withdrawals in the SDigital2 API

Customers

Customers represent the end-users who will be sending or receiving cryptocurrency through your integration.

Customer Management

Important: Customers are manually onboarded to SDigital2 by our team. You cannot create customers directly through the API.

Customer Onboarding Process:

Speak to the SDigital2 team about your customer onboarding requirements
The SDigital2 team will add customers to your organization
Once added, customers will automatically appear in your API customer list endpoints
Each customer receives unique wallet addresses across supported blockchain networks

Customer Properties

Core Information:

ID: Unique UUID identifier for API operations
Name: Customer's display name
Type: Either INDIVIDUAL or BUSINESS
Created/Updated: Timestamps for tracking

Wallet Information:

Wallet Addresses: Unique deposit addresses for each supported blockchain
Balances: Real-time token balances across all chains
Multi-Chain Support: Automatic address generation for all supported networks

Supported Blockchain Networks

Ethereum (ETHEREUM)
Polygon (POLYGON)
Base (BASE)
Arbitrum (ARBITRUM)

Example Customer Response

{
  "id": "774f7a53-fd45-4634-9548-eb37c9554137",
  "name": "John Doe",
  "type": "INDIVIDUAL",
  "createdAt": "2025-09-08T07:01:04.093Z",
  "updatedAt": "2025-09-08T07:01:04.084Z",
  "walletAddresses": [
    {
      "chain": "ARBITRUM",
      "walletAddress": "0xebe39cfda54886b2db0d4e7e4c63a4ccbc880f84",
      "balances": [
        {
          "currency": "USDC",
          "amount": "0",
          "updatedAt": "2025-09-12T22:56:00.648Z"
        },
        {
          "currency": "USDT",
          "amount": "0",
          "updatedAt": "2025-09-12T22:56:00.648Z"
        }
      ]
    },
    {
      "chain": "BASE",
      "walletAddress": "0x2fc4512d5859226cf0bf61fbbbdb5444fda60053",
      "balances": [
        {
          "currency": "USDC",
          "amount": "215.462157",
          "updatedAt": "2025-09-12T22:56:00.566Z"
        }
      ]
    },
    {
      "chain": "ETHEREUM",
      "walletAddress": "0xba1c64834804eac723776aa6addf216d307eb336",
      "balances": [
        {
          "currency": "USDC",
          "amount": "398.770344",
          "updatedAt": "2025-09-12T22:56:00.648Z"
        },
        {
          "currency": "USDT",
          "amount": "0",
          "updatedAt": "2025-09-12T22:56:00.648Z"
        }
      ]
    },
    {
      "chain": "POLYGON",
      "walletAddress": "0xbc87a12b0e9570bb5472d6066f220db7e98b709e",
      "balances": [
        {
          "currency": "USDC",
          "amount": "0",
          "updatedAt": "2025-09-12T22:56:00.594Z"
        },
        {
          "currency": "USDT",
          "amount": "0",
          "updatedAt": "2025-09-12T22:56:00.594Z"
        }
      ]
    }
  ]
}

Bank Accounts

Bank accounts represent PIX payment destinations for off-ramp transactions, allowing customers to receive Brazilian Real (BRL) funds from cryptocurrency conversions.

Bank Account Management

Bank accounts are created programmatically through the API and are linked to specific customers.

Bank Account Creation Process:

Create Bank Account - Submit bank account details including beneficiary information and PIX key
Verification - Bank account undergoes verification process with status tracking
Use in Transactions - Verified bank accounts can be used as destinations for off-ramp transactions

Bank Account Properties

Core Information:

ID: Unique UUID identifier for API operations
Customer ID: The customer this bank account belongs to
Name: Display name for the bank account
Type: Currently only EXTERNAL is supported
Created/Updated: Timestamps for tracking

Payment Details:

Rail: Payment rail type (currently only PIX is supported)
Currency: Supported currency (currently only BRL)
Account Details: PIX key information (key type and key value)
Beneficiary: Account holder information including legal name, tax ID, email, contact details, and address

Verification:

Status: Current verification status
Level: Verification level

PIX Key Types

Bank accounts support multiple PIX key types for receiving payments:

EMAIL - Email address as PIX key
PHONE - Phone number as PIX key
CNPJ - Brazilian company tax ID
RANDOM - Random PIX key (chave aleatória)

Example Bank Account Response

{
  "id": "3190d115-987f-402f-b558-0316d3a22ebd",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "name": "Main Business Account",
  "type": "EXTERNAL",
  "rail": "PIX",
  "currency": "BRL",
  "beneficiary": {
    "relationship": "SELF",
    "legalName": "John Doe",
    "taxId": "12345678900",
    "email": "john.doe@example.com",
    "incorporationDate": "2024-01-01",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310-100",
      "country": "BR"
    }
  },
  "accountDetails": {
    "keyType": "EMAIL",
    "keyValue": "john.doe@example.com"
  },
  "verification": {
    "status": "APPROVED",
    "level": "BASIC"
  },
  "createdAt": "2025-09-13T10:00:00.000Z",
  "updatedAt": "2025-09-13T10:00:00.000Z"
}

Verification Status: Bank accounts must be verified before they can be used in transactions. Monitor the verification status after creation and wait for approval before using the bank account in off-ramp operations.

Transactions

Transactions are the core of the SDigital2 API, enabling cryptocurrency-to-fiat (off-ramp) and fiat-to-cryptocurrency (on-ramp) conversions.

Transaction Types

OFF_RAMP (Crypto to Fiat):

Convert cryptocurrency (USDT/USDC) to Brazilian Real (BRL)
Funds are sent via PIX to a verified bank account
Requires sufficient cryptocurrency balance
Destination must specify a bankAccountId for the PIX payment

ON_RAMP (Fiat to Crypto):

Convert Brazilian Real (BRL) to cryptocurrency (USDT/USDC)
Customer makes PIX payment using provided PIX BR Code
Cryptocurrency is credited to customer's balance
Destination specifies the blockchain network and currency

Exchange Rate Locking

One of the key features of the SDigital2 API is exchange rate locking, which ensures price certainty for your users during the transaction process.

How Exchange Rate Locking Works

Request a Quote: Call the exchange rates endpoint with your desired conversion parameters
Receive Locked Rate: Get a time-limited quote with guaranteed exchange rates
Use in Transaction: Reference the quote ID when creating a transaction to lock in the rate
Price Protection: The locked rate is guaranteed regardless of market fluctuations during the lock period

Lock Duration Options

30 seconds (30s) - For quick transactions
1 minute (1m) - Standard duration
5 minutes (5m) - Extended time for complex flows

Exchange Rate Quote Example

{
  "id": "e4fdeef0-fdbd-4aeb-9669-9205d5455ae2",
  "sourceCurrency": "USDC",
  "sourceAmount": "100.000000",
  "destinationCurrency": "BRL",
  "destinationAmount": "524.20",
  "grossDestinationAmount": "535.17",
  "baseExchangeRate": "5.351740",
  "appliedExchangeRate": "5.242029",
  "fees": {
    "bps": "105",
    "flatAmount": "1",
    "totalAmount": "2.05",
    "currency": "USDC"
  },
  "expiresAt": "2025-09-13T08:12:04.695Z"
}

PIX Payment Timing: For PIX on-ramp flows, if funds are not sent before the quote expires but the customer still eventually sends the funds, an automatic refund will be sent back to the sending account. If the automatic refund doesn't occur, please reach out to the SDigital2 team for assistance.

Understanding the Base Exchange Rate

The baseExchangeRate is SDigital2's internal exchange rate used as the foundation for currency conversions. This is not the mid-market rate that you might see on financial websites or trading platforms.

Key Points about the Base Exchange Rate

Internal Rate: The baseExchangeRate is an internal SDigital2 rate, not the mid-market rate
Pre-Fee Rate: This is the base exchange rate before fees are applied
Market Hours Accuracy: During weekdays from 10 AM to 4 PM America/Sao_Paulo, the baseExchangeRate will be very close to the mid-market rate
No Guarantees Outside Market Hours: There are no guarantees about how close the rate will be to mid-market rates outside of business hours (evenings, nights) and on weekends
Fee Application: The final appliedExchangeRate includes all fees applied to the baseExchangeRate

Rate Timing Considerations

Optimal Timing: For the most competitive rates closest to mid-market prices, consider timing your transactions during São Paulo business hours (10 AM - 4 PM America/Sao_Paulo, Monday through Friday).

During Market Hours (10 AM - 4 PM America/Sao_Paulo, Weekdays):

Base exchange rates closely track mid-market rates
Most competitive pricing available

Outside Market Hours (Evenings, Nights, Weekends):

Rates may deviate more significantly from mid-market rates
Larger spreads may be applied to account for market volatility

Rate vs. Fee Structure

Understanding the relationship between different rate fields in exchange rate quotes:

baseExchangeRate - SDigital2's internal rate before any fees
appliedExchangeRate - Final rate after all fees are applied
grossDestinationAmount - Amount calculated using the base rate
destinationAmount - Final amount after fees are deducted

Supported Currencies

Cryptocurrencies:

USDT - Available on all supported chains (except Base)
USDC - Available on all supported chains

Fiat Currency:

BRL (Brazilian Real) - Via PIX payment rail only

Payment Rails

Cryptocurrency Rails:

Ethereum blockchain (ETHEREUM)
Polygon blockchain (POLYGON)
Base blockchain (BASE)
Arbitrum blockchain (ARBITRUM)

Fiat Payment Rail:

PIX - Brazilian instant payment system
- Supports all PIX key types: CPF, CNPJ, EMAIL, PHONE, RANDOM (chave aleatória)
- Instant transfers 24/7
- Real-time transaction confirmation

USDT
USDC

Supported Networks:

Ethereum (ETHEREUM)
Polygon (POLYGON)
Base (BASE)
Arbitrum (ARBITRUM)

Key Features:

Automatic transaction hash generation
Block explorer link generation
Real-time status tracking
Precision handling (6 decimal places)

Important Withdrawal Notes

Critical Requirements:

Withdrawals can only be made from existing customer balances
Ensure the destination wallet address matches the selected blockchain network
Withdrawal amounts are truncated to 6 decimal places
Verify wallet addresses carefully, transactions cannot be reversed

Withdrawal Process

Check Balance: Verify customer has sufficient balance
Validate Address: Ensure destination address is valid for the selected chain
Create Withdrawal: Submit withdrawal request with amount and destination
Monitor Status: Track withdrawal progress until completion
Receive Receipt: Get transaction hash and block explorer link

Example Withdrawal Response

{
  "id": "c2e3d98a-b40d-4d60-896e-ae7bb6716948",
  "customerId": "774f7a53-fd45-4634-9548-eb37c9554137",
  "currency": "USDC",
  "amount": "100",
  "chain": "ETHEREUM",
  "destinationWalletAddress": "0x2fc4512d5859226cf0bf61fbbbdb5444fda60053",
  "createdAt": "2025-09-13T18:01:00.764Z",
  "updatedAt": "2025-09-13T18:01:00.756Z",
  "status": "SUCCESS",
  "receipt": {
    "transactionHash": "0xb1189aa2a2c17eff237ece7a99bc284d70218ee13f3dea8e0027227d97244ca8",
    "blockExplorerUrl": "https://etherscan.io/tx/0xb1189aa2a2c17eff237ece7a99bc284d70218ee13f3dea8e0027227d97244ca8"
  }
}

Integration Patterns

Common Integration Flow

List Customers - Get available customers for your organization
Check Balances - Verify customer balances across chains
Get Exchange Rate - Lock in favorable rates for transactions
Create Transaction - Execute on-ramp or off-ramp operations
Monitor Progress - Track transaction status until completion
Handle Withdrawals - Move crypto to external wallets as needed

Best Practices

Rate Management:

Always use exchange rate locking for price certainty
Choose appropriate lock durations based on your UX flow
Handle quote expiration gracefully

Balance Management:

Check customer balances before creating transactions
Account for network fees in withdrawal calculations
Implement balance refresh mechanisms