Platform Accounts

Platform accounts are virtual accounts linked to a platfrom bank. They serve as the foundation for your bank's operations on the Cybrid platform, enabling your bank to hold fiat currencies and cryptocurrencies for executing trades, transfers, and other financial operations.

Overview

The Cybrid platform supports six types of platform accounts. Four are created by partners through the API, and two are automatically managed by the platform for billing and revenue tracking.

Partner-Created Accounts

You can create the following platform accounts using the Accounts API:

System-Managed Accounts

The platform automatically creates and manages these accounts for billing purposes:

⚠️

Compliance Restriction: Platform Accounts Are Not Pool Accounts

Financial services regulations require clear fund ownership and segregation. Platform accounts must not be used as pool accounts that service multiple customers' funds. Each platform account represents funds owned by either your bank or a single customer. For pooled funds belonging to multiple customers, use customer-level accounts with peer-to-peer transfer mechanisms.

Prerequisites

Before creating platform accounts:

1. Required OAuth Scope: accounts:execute
2. Bank Configuration: Your bank must be configured to support the asset type you're creating
3. Platform Support: The platform must support the asset in your environment (sandbox/production)

Account States

All accounts progress through these states:

ℹ️

State Polling

After calling POST /api/accounts, poll the account using /api/accounts/{account_guid} until the state transitions to created before proceeding with operations.

Create a Fiat Account

Fiat accounts hold traditional fiat currencies. Create a fiat account before funding your bank or processing fiat transfers.

Request

POST /api/accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "fiat",
  "asset": "USD",
  "name": "Primary USD Funding Account"
}

{
  "guid": "account_guid",
  "type": "fiat",
  "asset": "USD",
  "name": "Primary USD Funding Account",
  "bank_guid": "bank_guid",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "storing",
  "labels": [],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Parameters

⚠️

Bank-Level Accounts

Omit the customer_guid parameter to create a bank-level account. If you provide customer_guid, the account is created for that customer instead.

Handle Common Errors

Create Multiple Fiat Accounts

By default, banks can create one fiat account per currency. To create multiple fiat accounts per currency (e.g., separate accounts for different purposes), contact Cybrid Support to increase your limit.

If you attempt to create additional accounts without this configuration, you receive:

{
  "status": 409,
  "error_message": "Account(s) for asset already exists",
  "message_code": "data_exists"
}

ℹ️

Platform Accounts Cannot Be Deleted

Platform accounts cannot be deleted once created. Creating many platform accounts for temporary purposes results in a large number of permanent accounts, which adds management overhead to your bank.

Create a Trading Account

Trading accounts hold cryptocurrencies. Create a trading account before executing crypto buy/sell trades.

Request

POST /api/accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "trading",
  "asset": "USDC",
  "name": "USDC Trading Account"
}

{
  "guid": "account_guid",
  "type": "trading",
  "asset": "USDC",
  "name": "USDC Trading Account",
  "bank_guid": "bank_guid",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "storing",
  "labels": null,
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

ℹ️

Uniqueness Constraint

Only one trading account per cryptocurrency can exist at the bank level. Attempting to create a duplicate results in a 409 Conflict error.

Create a Storage Account

Storage accounts hold cryptocurrencies on-chain rather than in the trading system. Use storage accounts for long-term storage or withdrawal operations.

Request

POST /api/accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "storage",
  "asset": "USDC",
  "name": "USDC Cold Storage Account"
}

{
  "guid": "account_guid",
  "type": "storage",
  "asset": "USDC",
  "name": "USDC Cold Storage Account",
  "bank_guid": "bank_guid",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "storing",
  "labels": null,
  "created_at": "2024-01-15T10:40:00Z",
  "updated_at": "2024-01-15T10:40:00Z"
}

Parameters

Compare Storage and Trading Accounts

• Storage accounts hold assets on-chain with actual blockchain addresses
• Trading accounts hold assets within the Cybrid trading system for faster trade execution
• Each cryptocurrency can have one trading account and one storage account

Create an Invoice Operations Account

Invoice operations accounts pre-fund Lightning Network operations for your customers.

Request

POST /api/accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "invoice_operations",
  "asset": "BTC",
  "name": "Lightning Network Operations"
}

{
  "guid": "account_guid",
  "type": "invoice_operations",
  "asset": "BTC",
  "name": "Lightning Network Operations",
  "bank_guid": "bank_guid",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "storing",
  "labels": null,
  "created_at": "2024-01-15T10:45:00Z",
  "updated_at": "2024-01-15T10:45:00Z"
}

Parameters

ℹ️

Bank-Level Only

Invoice operations accounts can only be created at the bank level (not for customers) and are specifically for Lightning Network functionality.

Understand Gas Accounts

A gas account is a bank-level account that tracks network fees (also called gas fees) as a liability to the partner. The platform incurs these fees when executing on-chain cryptocurrency operations such as:

• Crypto withdrawals to external wallets
• Inter-account transfers between trading and storage accounts

ℹ️

Fiat Assets Only

Gas accounts can only be created for fiat assets (USD, CAD, etc.), not cryptocurrency assets. Network fees incurred on-chain are converted and tracked in the corresponding fiat gas account.

Learn How Gas Accounts Work

When you execute crypto operations that require on-chain transactions, the Cybrid Platform:

1. Calculates network fees - The platform estimates the gas fees required for the blockchain transaction
2. Includes fees in quotes - Network fees appear in the network_fee and network_fee_asset fields when you create a quote
3. Tracks as liability - Gas fees are recorded as a liability to the partner in the gas account
4. Settles monthly - Gas fees are either:
   • Invoiced to the partner at the beginning of each month, or
   • Partner can pay balance using fee revenue (if available)

Example: Crypto Withdrawal

When a customer withdraws ETH to an external wallet, the quote includes network fee information:

{
  "product_type": "crypto_transfer",
  "asset": "ETH",
  "side": "withdrawal",
  "receive_amount": 250000000000000000,
  "network_fee": 2900000000000000,
  "network_fee_asset": "ETH"
}

The network_fee of 0.0029 ETH (approximately $5 USD in this example) is tracked in the gas account as a cost to the partner.

Example: Inter-Account Transfer

When moving crypto between trading and storage accounts:

{
  "product_type": "inter_account",
  "asset": "BTC",
  "source_platform_account": "trading_account_guid",
  "destination_platform_account": "storage_account_guid",
  "deliver_amount": 10000000,
  "network_fee": 1000,
  "network_fee_asset": "BTC"
}

Network Fees by Operation Type

Consider Network Fee Behavior

• Network fee volatility: Gas fees fluctuate based on blockchain network conditions. The platform calculates fees at quote time, but actual costs may vary slightly by execution time.
• Asset-specific fees: Different cryptocurrencies have different fee structures. Bitcoin fees are typically measured in satoshis, while Ethereum fees are measured in wei.
• Batch operations: Operations like batch crypto withdrawals can optimize gas costs by combining multiple transfers into a single on-chain transaction.

Understand Fee Accounts

A fee account is a bank-level fiat account that accumulates trade fees collected from customer transactions. These fees represent revenue earned by the partner from trading activities on the platform.

Learn How Fee Accounts Work

When customers execute trades on the platform:

1. Trade fees are configured - Cybrid configures both platform fees and partner fees based on your partner agreement and partner preference
2. Fees are aggregated - All applicable fees are combined and shown in the fee field of quotes and trades
3. Fees are collected - Partner trade fees are automatically accumulated in the bank-level fee account
4. Settlement and billing - Accumulated fees are used to:
   • Offset other platform costs (like ACH fees, KYC fees, and gas fees)
   • Determine net amounts for monthly billing

Fee Types

Trade fees on the Cybrid Platform can include:

• Spread fees: Represented in basis points (e.g., 20 = 0.20% fee)
• Fixed fees: Represented in base units of the asset (e.g., 100 for USD = $1.00 fee)

Example: Trade Fee Accumulation

When a customer buys Bitcoin with USD:

{
  "product_type": "trading",
  "side": "buy",
  "asset": "BTC-USD",
  "deliver_amount": 10000000,
  "fee": 20000
}

The fee of $200 (20000 cents) accumulates in the fee account at the bank level.

Fee Account by Asset

Fee accounts can be created for different fiat currencies or cryptocurrencies:

• Fiat fee accounts: Standard fee accounts for USD, CAD, etc.
• Crypto fee accounts: Some operations may collect fees in crypto assets (e.g., USDC_NPL fee account for stablecoin swaps)

ℹ️

One Fee Account Per Asset

Only one fee account can exist per bank per asset combination. Fee accounts can be created for both fiat currencies (USD, CAD) and crypto assets (e.g., USDC for stablecoin swap fees).

Configure Fee Accounts

To set up fee accounts for specific assets:

1. Review your partner agreement to understand fee structures
2. Contact Cybrid Support to configure fee accounts for the required assets
3. Ensure proper bank configuration is in place before processing trades

Billing and Settlement

Understand How Gas and Fee Accounts Interact

At the end of each billing cycle:

1. Calculate net position:

   • Fee account balance (revenue from trades)
   • Minus: Gas account liability (costs for network fees)
   • Minus: Other costs (ACH fees, KYC fees, etc.)

2. Settlement:

   • If fee revenue exceeds costs: Partner may receive a credit or reduced invoice
   • If costs exceed fee revenue: Partner is invoiced for the net amount

Monthly Invoicing

The Cybrid finance team generates monthly invoices that include:

• Accumulated trade fees (from fee accounts)
• Network gas fees (from gas accounts)
• ACH and wire transfer fees
• KYC/KYB verification fees
• Other platform service costs

View Account Balances

Query fiat accounts for a specific customer using the Accounts API:

GET /api/accounts?type=fiat&customer_guid=your_customer_guid
Authorization: Bearer YOUR_TOKEN

To view all bank-level accounts:

GET /api/accounts?owner=bank
Authorization: Bearer YOUR_TOKEN

Withdraw Fees and Settle Gas

Settlement Requirement

Before withdrawing accumulated fees from your fee account to your bank-level fiat account, settle any outstanding gas liability. The platform enforces this through a balance check on the gas account.

⚠️

Settle Gas Before Withdrawing Fees

To withdraw fees, first transfer from your fee account to the gas account to pay off any outstanding liability. Only after the gas balance reaches zero can you transfer fees to your fiat account.

Valid Platform Account Transfers

The following transfer routes are permitted between platform accounts:

Best Practices

Create Accounts Effectively

• Use descriptive names: Include asset and purpose (e.g., USD Primary Funding Account)
• Use labels for organization: Labels help filter and organize accounts (e.g., ["production", "primary"])
• Poll for state changes: After creation, poll until state becomes created before using the account
• Create accounts early: Set up all required accounts during your bank configuration phase

Monitor Gas Costs

• Review network fee estimates: Check the network_fee field in quotes before executing crypto transfers
• Batch operations when possible: Use batch withdrawals on UTXO-based chains (like Bitcoin) to reduce per-transaction gas costs
• Consider timing: Network fees vary by time of day and network congestion; schedule large operations during low-traffic periods when feasible
• Track gas account balance: Monitor your gas account regularly to understand network fee trends

Optimize Fee Revenue

• Configure appropriate fee structures: Work with Cybrid to set competitive yet profitable fee structures
• Monitor fee account balance: Regular monitoring helps forecast revenue and understand customer trading patterns
• Understand fee calculations: Review the Trade Fees documentation to understand how fees are calculated and accumulated

Plan Finances

• Budget for gas costs: Network fees are variable; build buffer into financial planning
• Track monthly trends: Monitor both gas and fee accounts to understand monthly cost and revenue patterns
• Review invoices promptly: Cybrid invoices at the beginning of each month; review and reconcile with your account balances

Next Steps

• With a fiat account created, you can generate quotes and create funding deposits
• With a trading account created, you can execute crypto trades