Platform Accounts

This guide explains how to create bank-level platform accounts on the Cybrid Platform. Platform accounts enable your bank to hold fiat currencies and cryptocurrencies for executing trades, transfers, and other financial operations.

Overview

Platform accounts are bank-owned accounts that exist at the bank level rather than the customer level. They serve as the foundation for your bank's operations on the Cybrid platform.

You can create four types of platform accounts:

⚠️

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—never groups of customers. 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 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 customer_guid is provided, the account is created for that customer instead.

Common Errors

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'll 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 will result 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

Key Differences from 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.

Best Practices

• 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

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