FromChain Logo
API Reference

Sub-Accounts API

White-label your payment gateway by creating sub-accounts for your customers. Set custom markup fees and earn commissions on every transaction.

Overview

White-Label Gateway

Transform your platform into a payment gateway. Create unlimited sub-accounts for your customers, set your own markup fees, and earn commissions automatically on every transaction.

Unlimited Sub-Accounts

Create as many sub-accounts as you need, each with their own API key and custody wallet.

Custom Markup Fees

Set your own payin and payout markup fees on top of FromChain's base fees.

Individual API Keys

Each sub-account gets their own API key for secure, isolated access.

Fee Structure

The total fee charged to a sub-account is the sum of FromChain's base fee and your markup fee.

Total Fee = FromChain Base Fee + Gateway Markup

FromChain Base Fee:Configured per account
Your Markup:Configurable (e.g., 1%)
Total Fee:Base + Markup

💰 Example: If a sub-account receives a $100 payment:
• FromChain receives: Base fee (check your dashboard)
• Your gateway receives: Your markup fee
• Sub-account receives: Net amount after fees

Upgrade to Business Account

POST/v1/sub-accounts/upgrade

Upgrade your account to BUSINESS type to enable sub-account management

Request

upgrade-to-business.js
const response = await fetch('https://api.fromchain.plus/v1/sub-accounts/upgrade', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();

Response

upgrade-response.json
{
  "message": "Account upgraded to BUSINESS successfully",
  "tenantType": "BUSINESS"
}

Configure Gateway Fees

PATCH/v1/sub-accounts/gateway-fees

Update your markup fees for sub-accounts

Request Body

gatewayPayinFeePercentnumberrequired

Your markup fee for payins (e.g., 0.01 = 1%)

gatewayPayoutFeePercentnumberrequired

Your markup fee for payouts (e.g., 0.01 = 1%)

Request

configure-fees.js
const response = await fetch('https://api.fromchain.plus/v1/sub-accounts/gateway-fees', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer gw_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    gatewayPayinFeePercent: 0.01,  // 1% markup on payins
    gatewayPayoutFeePercent: 0.015 // 1.5% markup on payouts
  })
});

const result = await response.json();

Create Sub-Account

POST/v1/sub-accounts

Create a new sub-account for your customer

Request Body

namestringrequired

Name of the sub-account (e.g., customer's company name)

emailstringoptional

Email for the sub-account

Request

create-sub-account.js
const response = await fetch('https://api.fromchain.plus/v1/sub-accounts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation',
    email: 'payments@acme.com'
  })
});

const result = await response.json();

Response

create-sub-account-response.json
{
  "subAccount": {
    "id": "sub_abc123",
    "name": "Acme Corporation",
    "email": "payments@acme.com",
    "tenantType": "SUB_ACCOUNT",
    "custodyWalletAddress": "0x1234567890123456789012345678901234567890",
    "isActive": true,
    "createdAt": "2025-12-18T11:00:00.000Z"
  },
  "apiKey": "gw_live_sub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "message": "Sub-account created successfully. Save the API key securely - it won't be shown again!"
}

⚠️ Important: The API key is only shown once during creation. Make sure to save it securely and provide it to your customer.

List Sub-Accounts

GET/v1/sub-accounts

Retrieve a list of all your sub-accounts

Query Parameters

skipnumberdefault: 0

Number of records to skip for pagination

takenumberdefault: 20

Number of records to return (max 100)

Response

list-sub-accounts-response.json
{
  "subAccounts": [
    {
      "id": "sub_abc123",
      "name": "Acme Corporation",
      "email": "payments@acme.com",
      "custodyWalletAddress": "0x1234567890123456789012345678901234567890",
      "isActive": true,
      "balance": {
        "available": "1500.00",
        "pending": "250.00"
      },
      "invoiceCount": 45,
      "withdrawalCount": 12,
      "createdAt": "2025-12-18T11:00:00.000Z"
    }
  ],
  "total": 15,
  "skip": 0,
  "take": 20
}

Get Gateway Stats

GET/v1/sub-accounts/stats

Get aggregated statistics for your gateway

Response

gateway-stats-response.json
{
  "totalSubAccounts": 25,
  "activeSubAccounts": 22,
  "totalVolume": "150000.00",
  "totalGatewayFeesEarned": "1500.00"
}

Regenerate Sub-Account API Key

POST/v1/sub-accounts/:id/regenerate-api-key

Generate a new API key for a sub-account (invalidates the old one)

Response

regenerate-api-key-response.json
{
  "apiKey": "gw_live_sub_new_key_xxxxxxxxxxxxxxxxxx",
  "message": "API key regenerated successfully"
}

Deactivate Sub-Account

DELETE/v1/sub-accounts/:id

Deactivate a sub-account (preserves data but prevents access)

Response

deactivate-response.json
{
  "message": "Sub-account deactivated successfully"
}

⚠️ Warning: Deactivating a sub-account will immediately revoke their API access. Any pending invoices will still be processed, but new invoices cannot be created.

Complete Integration Example

Here's a complete example of setting up white-label payments for your platform:

white-label-integration.js
// 1. First, upgrade your account to BUSINESS
await fetch('https://api.fromchain.plus/v1/sub-accounts/upgrade', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer gw_live_your_gateway_key' }
});

// 2. Configure your markup fees
await fetch('https://api.fromchain.plus/v1/sub-accounts/gateway-fees', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer gw_live_your_gateway_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    gatewayPayinFeePercent: 0.01,  // 1% markup
    gatewayPayoutFeePercent: 0.01  // 1% markup
  })
});

// 3. Create a sub-account for your customer
const { apiKey } = await fetch('https://api.fromchain.plus/v1/sub-accounts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_your_gateway_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Customer Store',
    email: 'store@customer.com'
  })
}).then(r => r.json());

// 4. Give the apiKey to your customer - they can now create invoices
// When they receive payments:
// - FromChain fee (e.g., 0.5%) goes to FromChain
// - Your markup (e.g., 1%) goes to your custody wallet
// - Net amount goes to the customer's custody wallet

// 5. Monitor your earnings
const stats = await fetch('https://api.fromchain.plus/v1/sub-accounts/stats', {
  headers: { 'Authorization': 'Bearer gw_live_your_gateway_key' }
}).then(r => r.json());

console.log('Total markup fees earned:', stats.totalGatewayFeesEarned);