Skip to main content

​
Overview

This guide covers the complete flow for onboarding a new user (subaccount), including creation and KYC/KYB verification. To onboard a new user, you must create a subaccount. This is the first step before they can deposit funds or perform any banking operations.

​
Request

To create a subaccount, send a POST request to /v1/ramp/subaccount with the user’s email address. 
curl -X POST https://api.bullring.finance/v1/ramp/subaccount \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "email": "customer@example.com"
  }'

​
Response

The API will return the newly created subaccount’s details, including its unique id. 
{
  "id": "6a0fd7af-181d-4c0f-b24b-b8cfb739dabc",
  "email": "customer@example.com",
  "status": "created"
}

​
Webhooks

When a subaccount is created, you will receive a subaccount.status.created event. 
{
    "data": {
        "id": "6a0fd7af-181d-4c0f-b24b-b8cfb739dabc",
        "email": "customer@example.com",
        "status": "created"
    },
    "event": "subaccount.status.created"
}

​
Retrieving a Subaccount

You can check the balance and status of a subaccount at any time.

​
Request

curl https://api.bullring.finance/v1/ramp/subaccount/SUBACCOUNT_ID \
  -H "x-api-key: YOUR_API_KEY"

​
Response

The response includes the current balance and verification status. 
{
  "id": "6a0fd7af-181d-4c0f-b24b-b8cfb739d67a",
  "email": "customer@example.com",
  "balance": "100.00000000",
  "balanceCurrency": "USD",
  "status": "approved",
  "createdAt": "2025-11-19T23:59:29.241Z"
}

​
Listing Subaccounts

To view all your users, you can retrieve a paginated list of subaccounts.

​
Request

curl "https://api.bullring.finance/v1/ramp/subaccounts?page=1" \
  -H "x-api-key: YOUR_API_KEY"

​
Next Steps & Features

Once a subaccount is created, you can access the full suite of Bullring’s financial features for that user. Most of these operations require the subaccount to complete Verification.

​
1. Verification (KYC/KYB)

Before a subaccount can transact, they must verify their identity (Tier 1) or business (Tier 2/KYB).
  • Tier 1: Basic personal information. Grants access to NGN, GHS, and BRL transactions.
  • Tier 2: Comprehensive documentation for higher limits or business accounts. Grants access to USD, ZMW, and EUR transactions.
  • See Verification API

​
2. Deposits (On-Ramp)

Subaccounts can fund their balances using various methods:
  • Fiat: Local bank transfers, Mobile Money (e.g., NGN, GHS, ZMW).
  • Crypto: On-chain transfers (ETH, SOL) or Lightning Network (BTC).
  • See Deposits API

​
3. Withdrawals (Off-Ramp)

Subaccounts can withdraw their funds to:
  • Fiat Recipients: Wire transfers (USD, EUR), PIX (BRL), Mobile Money.
  • Crypto Wallets: Stablecoins (USDC, USDT) or Bitcoin.
  • See Withdrawals API

​
4. Recipient Management

Save beneficiary details (bank accounts, crypto addresses) to make repeated withdrawals easier and safer.

​
5. Rates & Fees

Check real-time conversion rates and calculate fees before initiating transactions to ensure transparency for your users.