Create and Execute a Trade

Overview

Executing a trade on the Cybrid Platform is a two-step flow. Generate a quote to lock in a price, then submit a trade against the quote guid. This guide walks through both endpoints, the trade state lifecycle, and common failure modes.

Prerequisites

• A customer with a verified identity
• A trading account in the asset you want to receive
• Sufficient balance in the source account (fiat to buy crypto, crypto to sell)

Step 1: Generate a quote

Generate a quote via POST /api/quotes. The quote provides a fixed price for a short window. Required fields:

• customer_guid — the customer's identifier (retrieve from GET /api/customers if needed)
• symbol — the trading pair in pair format (e.g., USDC-USD) — see GET /api/symbols for supported symbols
• side — buy or sell
• One of deliver_amount or receive_amount (not both) — see Choosing deliver amount vs receive amount below.

All amounts are in base units. USDC's base unit is 1/1,000,000 of a USDC (1,000,000 base units = 1 USDC). USD's base unit is the cent (10005 = $100.05).

ℹ️

Bank-level trading

To trade at the bank level instead of the customer level, provide bank_guid instead of customer_guid when creating the quote.

{
  "customer_guid": "customer_guid",
  "symbol": "USDC-USD",
  "side": "buy",
  "deliver_amount": 10000
}

{
  "guid": "quote_guid",
  "customer_guid": "customer_guid",
  "symbol": "USDC-USD",
  "side": "buy",
  "receive_amount": 100000000,
  "deliver_amount": 10000,
  "fee": 0,
  "issued_at": "2022-05-11T19:47:52.048Z",
  "expires_at": "2022-05-11T19:48:22.048Z"
}

⚠️

Quote validity

Quotes are valid for 30 seconds. Use the expires_at field on the quote response to determine when a quote expires. Trades against expired quotes fail.

Choosing deliver amount vs receive amount

Provide one of deliver_amount or receive_amount on the quote — not both:

• deliver_amount — fixes the amount you send (the source asset). Fees come out of the destination side, so the recipient receives less than the unfee'd exchange rate would provide. Use when the sender's outflow is fixed.
• receive_amount — fixes the amount the recipient gets (the destination asset). The platform increases the sender's input on the source side to cover fees. Use when the recipient's inflow is fixed.

For trades the source and destination are different assets (e.g., USD → USDC); for funding, book, crypto, and inter-account transfers they are the same asset and fees reduce the credited amount in that single asset.

Examples in this guide and the related Transfers guides use deliver_amount by default. See Trade fees for the full buy/sell fee math.

Step 2: Execute the trade

Execute the trade via POST /api/trades. The only required field is the quote guid:

{
  "quote_guid": "quote_guid"
}

{
  "guid": "trade_guid",
  "customer_guid": "customer_guid",
  "quote_guid": "quote_guid",
  "symbol": "USDC-USD",
  "side": "buy",
  "state": "storing",
  "receive_amount": 100000000,
  "deliver_amount": 10000,
  "fee": 0,
  "created_at": "2022-05-11T19:56:42.856Z"
}

Step 3: Check trade status

Poll GET /api/trades/{trade_guid} to verify the trade completed:

{
  "guid": "trade_guid",
  "customer_guid": "customer_guid",
  "quote_guid": "quote_guid",
  "symbol": "USDC-USD",
  "side": "buy",
  "state": "completed",
  "receive_amount": 100000000,
  "deliver_amount": 10000,
  "fee": 0,
  "created_at": "2022-05-11T19:56:42.856Z"
}

Trade states

ℹ️

Sandbox limitation

In sandbox, trades reach executed and do not transition to settling or completed. Funds are still made available for downstream testing even though platform_available does not reflect the trade. See Sandbox trades for details.

⚠️

Trade failures

Trades may fail if the market price moves outside the allowed spread between quote generation and trade execution. In some cases, adjusting the BPS (basis points, the fee or spread) can help a trade succeed by increasing the tolerance for price movement. Contact support if you need to temporarily adjust BPS to facilitate a trade.

ℹ️

USDC off-ramp

Direct transfers from USDC (crypto) to an external bank account (such as via Plaid) are not supported. To off-ramp USDC to a bank account, first convert USDC to USD using a trade, then withdraw USD to your external bank account using a funding transfer.