OTC Crypto Operations

Managing an OTC (Over-The-Counter) desk or a multi-exchange crypto strategy requires tracking balances across dozens of external venues (Binance, Coinbase, Kraken) while maintaining a centralized source of truth for your business accounting.

In Beetles, you model this by treating each Asset as a Ledger and each Exchange as an Account within those ledgers, all grouped under a single Identity.

Architecture

To see the "Final Balance" across all exchanges, you leverage the Identity entity. An Identity links your various accounts together, allowing you to query a consolidated view while maintaining granular exchange-level tracking.

Entity Setup

Create Asset Ledgers

Each crypto asset or fiat currency should be its own ledger. This ensures that the engine enforces decimal precision and double-entry rules per asset.

BTC Ledger

curl -X POST http://localhost:8080/v1/ledgers 
  -d '{ "name": "Bitcoin (BTC)" }'

USDT Ledger

curl -X POST http://localhost:8080/v1/ledgers 
  -d '{ "name": "Tether (USDT)" }'

Create Business Identity

The Identity represents your company or specific OTC desk.

Create Identity

curl -X POST http://localhost:8080/v1/identities 
  -d '{ "label": "Global OTC Desk" }'

Create and Link Exchange Accounts

Create accounts for each exchange within the relevant ledgers and link them to your Identity.

Binance BTC Account

curl -X POST http://localhost:8080/v1/accounts 
  -d '{ 
    "name": "Binance:BTC", 
    "ledger_id": "BTC_LEDGER_ID",
    "identity_id": "OTC_DESK_ID"
  }'

Coinbase BTC Account

curl -X POST http://localhost:8080/v1/accounts 
  -d '{ 
    "name": "Coinbase:BTC", 
    "ledger_id": "BTC_LEDGER_ID",
    "identity_id": "OTC_DESK_ID"
  }'

Common Operations

1. External Exchange Trade (Buy BTC with USDT)

When you execute a trade on Binance, you record it in Beetles as an Exchange across your Binance accounts. The system uses your Identity to automatically find the correct BTC account linked to the same entity.

POST /v1/exchanges

curl -X POST http://localhost:8080/v1/exchanges 
  -d '{
    "source_account_id": "BINANCE_USDT_ID",
    "destination_ledger_id": "BTC_LEDGER_ID",
    "amount": 50000000000, # 50,000 USDT (assuming 6 decimals)
    "exchange_rate": 50000,
    "code": 100 # Code for "Trade: Buy"
  }'

Result:

BINANCE_USDT is debited.
BINANCE_BTC is credited (automatically resolved via the Identity).

2. Inter-Exchange Transfer (Withdrawal)

Moving assets from Binance to Coinbase is a simple transfer within the same ledger.

POST /v1/transfers

curl -X POST http://localhost:8080/v1/transfers 
  -d '{
    "debit_account_id": "BINANCE_BTC_ID",
    "credit_account_id": "COINBASE_BTC_ID",
    "amount": 100000000, # 1.0 BTC (assuming 8 decimals)
    "code": 200 # Code for "Inter-Exchange Transfer"
  }'

Consolidated Reporting

The power of this model is the ability to see your Net Position across all venues in real-time.

Query Balances by Identity

By querying the Identity, you get a breakdown of every account linked to it, grouped by ledger.

GET /v1/identities/OTC_DESK_ID/balances

curl http://localhost:8080/v1/identities/$OTC_DESK_ID/balances

Response

{
  "identity_id": "01969...",
  "label": "Global OTC Desk",
  "balances": [
    {
      "ledger_name": "Bitcoin (BTC)",
      "total_balance": 1500000000,
      "accounts": [
        { "name": "Binance:BTC", "balance": 900000000 },
        { "name": "Coinbase:BTC", "balance": 600000000 }
      ]
    },
    {
      "ledger_name": "Tether (USDT)",
      "total_balance": 250000000000,
      "accounts": [
        { "name": "Binance:USDT", "balance": 150000000000 },
        { "name": "Coinbase:USDT", "balance": 100000000000 }
      ]
    }
  ]
}

Business Accounting (P&L Tracking)

To track profit and loss (P&L), you can introduce Internal Equity and Expense ledgers. This separates your operational liquidity (on exchanges) from your business performance.

1. Setup Accounting Ledgers

Fees Ledger

curl -X POST http://localhost:8080/v1/ledgers -d '{ "name": "Trading Fees (Expense)" }'

Realized P&L Ledger

curl -X POST http://localhost:8080/v1/ledgers -d '{ "name": "Realized P&L (Equity)" }'

2. The Full Trade Lifecycle

When you perform a trade, you have three distinct dimensions to track:

Inventory Change: Assets moving across ledgers.
Slippage/Fees: Costs paid to the venue.
Realized Gain/Loss: The delta in your net worth.

3. Correlation & Auditing

To track which fee belongs to which trade, use the reference and metadata fields. This allows you to reconstruct the entire trade lifecycle during audits.

POST /v1/transfers (The Atomic Bundle)

curl -X POST http://localhost:8080/v1/transfers \
  -d '{
    "transfers": [
      {
        "debit_account_id": "BINANCE_USDT_ID",
        "credit_account_id": "WORLD_USDT_ID",
        "amount": 100000000,
        "code": 100,
        "reference": "trade:uuid-789",
        "metadata": { "exchange_order_id": "BIN-12345" },
        "linked": true
      },
      {
        "debit_account_id": "BINANCE_USDT_ID",
        "credit_account_id": "BINANCE_FEES_ID",
        "amount": 100000,
        "code": 500,
        "reference": "fee:uuid-789",
        "metadata": { "parent_trade": "trade:uuid-789" },
        "linked": false
      }
    ]
  }'

By using the same reference suffix or a common ID in metadata, you can query all related legs of a single operational event.

4. Realizing Profit (Arbitrage Example)

If you buy 1 BTC for 50k USDT on Binance and sell it for 51k USDT on Coinbase, you have a realized profit of 1k USDT.

Record Profit

curl -X POST http://localhost:8080/v1/transfers \
  -d '{
    "debit_account_id": "COINBASE_USDT_ID",
    "credit_account_id": "TRADING_PROFIT_ID",
    "amount": 1000000000, # 1,000 USDT profit
    "code": 600, # Code for "Realized Profit"
    "reference": "arb-trade-01969..."
  }'

By querying the Realized P&L Ledger, you can see your total business performance regardless of which exchange the money is currently sitting in.

Double-Entry Tip: In this model, the Trading Profit account acts as an Equity account. When you credit it, you are acknowledging that your business's net worth has increased.

Always ensure that the amount in your transfers matches the decimal precision of the ledger. BTC typically uses 8 decimals ($10^8$), while USDT typically uses 6 ($10^6$).

OTC Crypto Operations

On this page