Guides

Creating a Trading Account and Executing a Trade

This guide explains how to create a segregated trading account for buying, selling, and holding crypto assets, then execute trades with guaranteed pricing.

Overview

Trading accounts enable customers to:

  • Buy and sell crypto assets (BTC, SOL, ETH)
  • Hold crypto positions separate from main account
  • Execute trades with real-time pricing
  • Maintain regulatory compliance through segregation
  • Access professional trading features

The trading process involves:

  1. Creating a segregated trading account
  2. Funding the account with stablecoins
  3. Getting price quotes for trades
  4. Executing trades with guaranteed pricing
  5. Managing positions and withdrawals

Prerequisites

  • Acceptance of trading provider terms of service
  • Completed enhanced KYC for trading (may be required)
  • Valid api key

Part 1: Creating a Trading Account

Step 1: Create the Trading Account

POST /trading-accounts
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "bankAccountId": "DDA123456789",
  "bankAccountType": "checking"
}

Request Parameters

ParameterTypeRequiredDescription
bankAccountIdstringYesReference to the underlying bank account in the bank's core system
bankAccountTypestringYesType of the linked bank account (checking or savings)

Example Response

{
  "id": "TDA_01BX5ZZKBKACTAV9WEVGEMMVS1",
  "bankAccountId": "DDA123456789",
  "bankAccountType": "checking"
}

Save the trading account ID for subsequent operations.

Step 2: Fund Your Trading Account

Transfer funds from the customer's DDA to enable trading:

POST /trading-accounts/{trading-account-id}/deposits
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "amount": "1000.00",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  }
}

Funding Options

Using Stablecoins

{
  "amount": "5000.00",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  }
}

Using Deposit Tokens

{
  "amount": "2500.00",
  "currency": {
    "type": "deposit-token-currency",
    "id": "DPT_01BX5ZZKBKACTAV9WEVGEMMVS1"
  }
}

Step 3: Verify Account Balance

Check the trading account balance:

GET /trading-accounts/{trading-account-id}/token-balances
Authorization: Bearer {your-api-key}

Example Response

{
  "data": [
    {
      "token": {
        "symbol": "USDC",
        "network": "solana"
      },
      "amount": "1000.00"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Part 2: Executing a Trade

Step 1: Check Market Prices

Get current market data for available trading pairs:

GET /trading/markets?filter[name]=sol-usd,btc-usd,eth-usd
Authorization: Bearer {your-api-key}

Example Response

{
  "data": [
    {
      "marketName": "sol-usd",
      "network": "solana",
      "currentPrice": "98.50",
      "yesterdaysPrice": "95.20",
      "at": "2024-03-15T14:30:00Z"
    },
    {
      "marketName": "btc-usd",
      "network": "bitcoin",
      "currentPrice": "67500.00",
      "yesterdaysPrice": "66800.00",
      "at": "2024-03-15T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

Step 2: Generate Price Quote

Get a guaranteed price quote for the trade:

POST /trading/markets/sol-usd/quotes?side=buy
Authorization: Bearer {your-api-key}

{
  "amount": "500.00",
  "side": "buy"
}

Example Response

{
  "data": [
    {
      "id": "QTE_01BX5ZZKBKACTAV9WEVGEMMVS1",
      "marketName": "sol-usd",
      "side": "buy",
      "price": "98.75",
      "assetBought": {
        "symbol": "SOL",
        "network": "solana",
        "amount": "5.065"
      },
      "assetSold": {
        "symbol": "USD",
        "network": "fiat",
        "amount": "500.00"
      },
      "created": "2024-03-15T14:30:00Z",
      "expires": "2024-03-15T14:35:00Z",
      "fees": {
        "flat": "2.50",
        "bps": 25
      }
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Step 3: Execute the Trade

Use the quote to execute your trade with guaranteed pricing:

POST /trading/quotes/{quote-id}
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "tradingAccountId": "TDA_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

Request Parameters

ParameterTypeRequiredDescription
tradingAccountIdstringYesTrading account to execute trade in

Example Response

{
  "type": "trade-execution-transaction",
  "id": "TXN_01BX5ZZKBKACTAV9WEVGEMMVS1",
  "status": "processing",
  "market": "sol-usd",
  "side": "buy",
  "price": "98.75",
  "amount": "500.00",
  "created": "2024-03-15T14:31:00Z",
  "updated": "2024-03-15T14:31:00Z"
}

Monitoring and Management

Check Trade Status

Monitor the trade execution:

GET /trading-accounts/{trading-account-id}/trades/{trade-id}
Authorization: Bearer {your-api-key}

List All Trades

View complete trading history:

GET /trading-accounts/{trading-account-id}/trades
Authorization: Bearer {your-api-key}

Cancel Pending Trade

Cancel a trade that hasn't executed yet:

POST https://sandbox.omnia.financial/trading-accounts/{id}/trades/{tradeId}/cancellations
Authorization: Bearer {your-api-key}

Check Portfolio Balance

View all token holdings:

GET /trading-accounts/{trading-account-id}/token-balances
Authorization: Bearer {your-api-key}

Example Portfolio Response

{
  "data": [
    {
      "token": {
        "symbol": "USDC",
        "network": "solana"
      },
      "amount": "500.00"
    },
    {
      "token": {
        "symbol": "SOL",
        "network": "solana"
      },
      "amount": "5.065"
    },
    {
      "token": {
        "symbol": "BTC",
        "network": "bitcoin"
      },
      "amount": "0.0296"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 20
  }
}

Withdrawing from Trading Account

Move funds back to the customer's DDA:

POST /trading-accounts/{trading-account-id}/withdrawals
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "amount": "250.00",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  }
}

Error Handling

Insufficient Funds

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "Trading account balance insufficient",
  "details": {
    "available": "250.00",
    "required": "500.00",
    "currency": "USDC"
  }
}

Quote Expired

{
  "error": "QUOTE_EXPIRED",
  "message": "Price quote has expired",
  "details": {
    "quoteId": "QUOTE_123",
    "expiredAt": "2024-03-15T14:35:00Z",
    "suggestion": "Generate a new quote"
  }
}

Market Closed

{
  "error": "MARKET_UNAVAILABLE",
  "message": "Trading market temporarily unavailable",
  "details": {
    "market": "btc-usd",
    "reason": "MAINTENANCE",
    "estimatedResolution": "2024-03-15T16:00:00Z"
  }
}

Integration Example

React Trading Component

const TradingWidget = () => {
  const [quote, setQuote] = useState(null);
  const [amount, setAmount] = useState('');
  const [market, setMarket] = useState('sol-usd');
  const [side, setSide] = useState('buy');

  const getQuote = async () => {
    const response = await fetch(`/trading/markets/${market}/quotes`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount,
        side,
      }),
    });
    const data = await response.json();
    setQuote(data.data[0]);
  };

  const executeTrade = async () => {
    if (!quote) return;

    const response = await fetch(`/trading/quotes/${quote.id}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        tradingAccountId: 'TDA_01BX5ZZKBKACTAV9WEVGEMMVS1',
      }),
    });

    const trade = await response.json();
    console.log('Trade executed:', trade);
  };

  return (
    <div>
      <select value={market} onChange={(e) => setMarket(e.target.value)}>
        <option value="sol-usd">SOL/USD</option>
        <option value="btc-usd">BTC/USD</option>
        <option value="eth-usd">ETH/USD</option>
      </select>

      <select value={side} onChange={(e) => setSide(e.target.value)}>
        <option value="buy">Buy</option>
        <option value="sell">Sell</option>
      </select>

      <input value={amount} onChange={(e) => setAmount(e.target.value)} placeholder="Amount" />

      <button onClick={getQuote}>Get Quote</button>

      {quote && (
        <div>
          <p>Price: ${quote.price}</p>
          <p>Expires: {new Date(quote.expires).toLocaleTimeString()}</p>
          <button onClick={executeTrade}>Execute Trade</button>
        </div>
      )}
    </div>
  );
};

API Reference

Trading Account Management

  • Create Account: POST /trading-accounts
  • Fund Account: POST /trading-accounts/{id}/deposits
  • Withdraw Funds: POST /trading-accounts/{id}/withdrawals
  • Check Balances: GET /trading-accounts/{id}/token-balances

Trading Operations

  • Get Markets: GET /trading/markets
  • Generate Quote: POST /trading/markets/{market}/quotes
  • Execute Trade: POST /trading/quotes/{id}
  • List Trades: GET /trading-accounts/{id}/trades
  • Cancel Trade: DELETE /trading-accounts/{id}/trades/{tradeId}

Updated 10 months ago

Did this page help you?