Getting Started

Endpoints

You can use the following endpoints to access our hosted API:

REST endpoint: https://prod.astra-api.dev/v2
WebSocket endpoint: wss://prod.astra-api.dev/v2

Authentication

All requests to Astra API need to be authenticated with the x-astra-api-key header

You can generate an API key at https://terminal.astra-api.dev/settings/apikey. Set the header x-astra-api-key to the value of your API key.

{
    "x-astra-api-key": "KjUBAhdIafaDFSCsajfaIowSADxkaw"
}

Private REST API

Some endpoints may require you to provide your account ID. You can find this at https://terminal.astra-api.dev/settings/profile

Get Balances

GET /balances/{account_id}

Fetches the balances of this account. Returns a mapping of instrument IDs to their balance details.

If you have a balances in a blockchain token, the response will contain fields identifying the network and contract address of the token.

Some instruments, like popular stablecoins (USDC, USDT) and native tokens (BTC, ETH), are considered blockchain-agnostic in our systems, and will show up without a network or address.

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to fetch balances for

{
  "123e4567-e89b-12d3-a456-426614174000": {
    "instrumentId": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "BTC",
    "amount": "1.21",
    "network": null,
    "address": null 
  },
  "456e7890-e89b-12d3-a456-426614174001": {
    "instrumentId": "456e7890-e89b-12d3-a456-426614174001",
    "symbol": null,
    "amount": "5.67",
    "network": "ethereum",
    "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"
  },
  "789e0123-e89b-12d3-a456-426614174002": {
    "instrumentId": "789e0123-e89b-12d3-a456-426614174002",
    "symbol": "USD",
    "amount": "10.11",
    "network": null,
    "address": null
  }
}

Response

The response is a JSON object where: - Keys are instrument IDs (UUIDs) - Values are balance objects containing detailed information about each asset

Name	Type	Description
instrumentId	UUID	The unique identifier for the instrument
symbol	String or null	The symbol of the asset (e.g., "BTC", "ETH", "SOL")
amount	String	The current balance amount as a decimal string
network	String or null	The blockchain network for this asset (e.g., "bitcoin", "ethereum", "solana")
address	String or null	The contract address for this token on the specified network

Get Transfer History

GET /transfers/{account_id}

Fetches all transfers (deposits and withdrawals) for a specific account. Returns a list of transfers with their amounts, types, and transaction details.

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to fetch transfers for

[
  {
    "id": "226",
    "createdAt": "2024-01-15T10:30:00Z",
    "symbol": "BTC",
    "amount": "0.001",
    "transferType": "deposit",
    "metadata": null,
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "225",
    "createdAt": "2024-01-14T15:20:00Z",
    "symbol": "ETH",
    "amount": "1.5",
    "transferType": "withdrawal",
    "metadata": {
      "type": "withdrawal",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "network": "ethereum",
      "withdrawal_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "updatedAt": "2024-01-14T15:20:00Z"
  }
]

Response

The response is a JSON array of transfer objects, ordered by creation date (most recent first).

Name	Type	Description
id	String	Unique identifier for the transfer (integer as string)
createdAt	String	ISO 8601 timestamp when the transfer was created
symbol	String	The asset symbol being transferred (e.g., "BTC", "ETH", "USDC")
amount	String	The amount transferred (as decimal string)
transferType	String	Type of transfer: "deposit" or "withdrawal"
metadata	Object or null	Additional metadata associated with the transfer. For withdrawals: contains type, address, network, and withdrawal_id. For deposits: may contain transaction details (tx object with hex, txid, vout) or be null
updatedAt	String	ISO 8601 timestamp when the transfer was last updated

Transfer Types

Type	Description
deposit	Incoming transfer that credits the account
withdrawal	Outgoing transfer that debits the account

Get OTC History

GET /converts/{account_id}

Fetches the OTC trade history for a specific account. We also use the term "convert" or "swap" to refer to an OTC trade in some places.

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to fetch OTC history for

[
  {
    "displayId": "550e8400-e29b-41d4-a716-446655440000",
    "id": 123,
    "takerAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "makerAccountId": "550e8400-e29b-41d4-a716-446655440001",
    "buyInstrumentId": "550e8400-e29b-41d4-a716-446655440002",
    "buyQuantity": "1.5",
    "buyTxnId": 456,
    "sellInstrumentId": "550e8400-e29b-41d4-a716-446655440003",
    "sellQuantity": "0.001",
    "sellTxnId": 457,
    "category": "otc",
    "notes": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "buySymbol": "ETH",
    "sellSymbol": "BTC"
  }
]

Response

The response is a JSON array of OTC trade objects, ordered by creation date (most recent first).

Name	Type	Description
displayId	String	Unique display identifier for the trade (UUID)
id	Integer	Internal trade ID
takerAccountId	String	Account ID of the trade taker (the requesting account)
makerAccountId	String	Account ID of the trade maker (counterparty)
buyInstrumentId	String	Instrument ID for the asset being bought
buyQuantity	String	Quantity of the asset being bought (as decimal string)
buyTxnId	Integer or null	Transaction ID for the buy side
sellInstrumentId	String	Instrument ID for the asset being sold
sellQuantity	String	Quantity of the asset being sold (as decimal string)
sellTxnId	Integer or null	Transaction ID for the sell side
category	String or null	Trade category (e.g., "otc")
notes	String or null	Additional notes about the trade
createdAt	String	ISO 8601 timestamp when the trade was created
updatedAt	String	ISO 8601 timestamp when the trade was last updated
buySymbol	String	Symbol of the asset being bought (e.g., "ETH", "BTC")
sellSymbol	String	Symbol of the asset being sold (e.g., "ETH", "BTC")

Get Transaction History

GET /transactions/{account_id}

Fetches the full raw transaction history for a specific account. Any operation that credits or debits this account is considered a "transaction". So deposits, withdrawals, and fees will all show up as transactions, OTC trades will show up as two transactions (one for each asset involved in the trade). This endpoint is usually only used for things like reporting, balance reconciliation, etc. To get more detailed info about specific types of transactions, see the following endpoints:

Get OTC History,
Get Transfer History
Get Withdrawal Requests

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to fetch transaction history for

[
  {
    "displayId": "550e8400-e29b-41d4-a716-446655440000",
    "instrumentId": "550e8400-e29b-41d4-a716-446655440001",
    "symbol": "BTC",
    "amount": "0.001",
    "debitFrom": "550e8400-e29b-41d4-a716-446655440002",
    "creditTo": "550e8400-e29b-41d4-a716-446655440000",
    "notes": "Deposit",
    "createdAt": "2024-01-15T10:30:00Z",
    "idemKey": "deposit_123",
    "type": "deposit",
    "tradeDisplayId": null
  },
  {
    "displayId": "550e8400-e29b-41d4-a716-446655440003",
    "instrumentId": "550e8400-e29b-41d4-a716-446655440004",
    "symbol": "ETH",
    "amount": "1.5",
    "debitFrom": "550e8400-e29b-41d4-a716-446655440000",
    "creditTo": "550e8400-e29b-41d4-a716-446655440005",
    "notes": "OTC Trade",
    "createdAt": "2024-01-14T15:20:00Z",
    "idemKey": "trade_456",
    "type": "trade",
    "tradeDisplayId": "550e8400-e29b-41d4-a716-446655440006"
  }
]

Response

The response is a JSON array of transaction objects, ordered by creation date (most recent first).

Name	Type	Description
displayId	String	Unique display identifier for the transaction (UUID)
instrumentId	String	Instrument ID for the asset involved in the transaction
symbol	String	Symbol of the asset (e.g., "BTC", "ETH", "USDC")
amount	String	Transaction amount (as decimal string)
debitFrom	String	Account ID that was debited (money taken from)
creditTo	String	Account ID that was credited (money given to)
notes	String or null	Additional notes about the transaction
createdAt	String	ISO 8601 timestamp when the transaction was created
idemKey	String or null	Idempotency key for the transaction
type	String or null	Transaction type: "deposit", "withdrawal", "trade", "fee", or null
tradeDisplayId	String or null	Display ID of the associated trade (if this transaction is part of a trade)

Transaction Types

Type	Description
deposit	Incoming funds to the account
withdrawal	Outgoing funds from the account
trade	Transaction related to a trade (buy/sell)
fee	Fee charged for a service
null	Other transaction types or legacy transactions

Get Withdrawal Requests

GET /withdrawal-request/{account_id}/all

Fetches all withdrawal requests for a specific account. Returns a list of withdrawal requests with their current status, amounts, and transaction details.

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to fetch withdrawal requests for

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2024-01-15T10:30:00Z",
    "symbol": "BTC",
    "amount": "0.5",
    "transferType": "withdrawal",
    "status": "completed",
    "metadata": null,
    "updatedAt": "2024-01-15T10:35:00Z",
    "network": "bitcoin",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "error": null,
    "networkTxId": "0x1234567890abcdef1234567890abcdef12345678"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "createdAt": "2024-01-14T15:20:00Z",
    "symbol": "ETH",
    "amount": "2.0",
    "transferType": "withdrawal",
    "status": "processing",
    "metadata": null,
    "updatedAt": "2024-01-14T15:25:00Z",
    "network": "ethereum",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "error": null,
    "networkTxId": null
  }
]

Response

The response is a JSON array of withdrawal request objects, ordered by creation date (most recent first).

Name	Type	Description
id	String	Unique identifier for the withdrawal request (UUID)
createdAt	String	ISO 8601 timestamp when the withdrawal request was created
symbol	String	The asset symbol being withdrawn (e.g., "BTC", "ETH", "USDC")
amount	String	The amount to be withdrawn (as decimal string)
transferType	String	Always "withdrawal" for withdrawal requests
status	String	Current status of the withdrawal request
metadata	Object or null	Additional metadata associated with the withdrawal
updatedAt	String	ISO 8601 timestamp when the withdrawal request was last updated
network	String	The blockchain network for the withdrawal (e.g., "bitcoin", "ethereum")
address	String	The destination address for the withdrawal
error	String or null	Error message if the withdrawal failed
networkTxId	String or null	The blockchain transaction ID (prefixed with "0x" for Ethereum)

Withdrawal Status Values

Status	Description
pending	Withdrawal request is pending approval
processing	Withdrawal is being processed
sent	Withdrawal has been sent to the blockchain
completed	Withdrawal has been confirmed on the blockchain
failed	Withdrawal failed due to an error

Create Withdrawal Request

POST /withdrawal-request/{account_id}

Creates a new withdrawal request for a specific account. The withdrawal will begin processing immediately. You can track the status using the Get Withdrawal Requests endpoint

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to create the withdrawal request for

Request Body

Field	Type	Required	Description
instrumentSymbol	String	True	The asset symbol to withdraw (e.g., "BTC", "ETH", "USDC")
amount	String	True	The amount to withdraw (as decimal string)
network	String	True	The blockchain network for the withdrawal (e.g., "bitcoin", "ethereum", "base")
address	String	True	The destination address for the withdrawal

{
  "instrumentSymbol": "BTC",
  "amount": "0.001",
  "network": "bitcoin",
  "address": "bc1qexample1234567890abcdef1234567890"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Response

Name	Type	Description
id	String	Unique identifier for the withdrawal request (UUID)

Get Deposit Address

GET /deposit-address/{account_id}

Fetches the deposit address for a specific account and network. Returns the address where users can send funds to be credited to their account.

Request

Parameter	Type	Required	Description
account_id	UUID	True	The account ID to get the deposit address for
network	String	True	The blockchain network (e.g., "bitcoin", "ethereum", "base")

GET /deposit-address/{account_id}?network=bitcoin

{
  "address": "bc1qexample1234567890abcdef1234567890"
}

Response

Name	Type	Description
address	String	The deposit address for the specified network

Networks

Network	Description
bitcoin	Bitcoin network
ethereum	Ethereum mainnet (coming soon)
base	Base network (coming soon)
arbitrum	Arbitrum network (coming soon)
solana	Solana network (coming soon)
avalanche	Avalanche C-Chain (coming soon)
optimism	Optimism network (coming soon)
polygon	Polygon network (coming soon)
bsc	Binance Smart Chain (coming soon)
algorand	Algorand network (coming soon)
noble	Noble network (coming soon)
stellar	Stellar network (coming soon)
sui	Sui network (coming soon)

Get Express Deposit Address

GET /express-deposit-address

Fetches the express deposit address for a specific coin and network. Express deposits are processed faster, but must be sent from a linked address.

Express deposits have the following requirements:

Must be sent from a linked address
For UTXO chains (Bitcoin, etc.), all input UTXOs must be from linked addresses
Processed faster than standard deposits

Request

Parameter	Type	Required	Description
coin	String	True	The coin symbol (e.g., "BTC", "ETH", "USDC")
network	String	True	The blockchain network (e.g., "bitcoin", "ethereum", "base")

{
  "address": "bc1qexample1234567890abcdef1234567890"
}

Response

Name	Type	Description
address	String	The express deposit address for the specified coin and network

OTC

Stream quotes

/ws/stream-otc-quotes/{account_id}?from=BTC&to=USD&fromQty=1.25

{
    "quote": {
        "quoteId": "a0743434-66c8-49b7-aca2-46c910a54cf1",
        "accountId": "a0743434-66c8-49b7-aca2-46c910a54cf1",
        "fromAsset": "BTC",
        "toAsset": "USD",
        "fromAssetQuantity": 1.25,
        "toAssetQuantity": 81436.0875,
        "expiryTime": 1733561867046245,
        "signature": "6932874cf486617239c7d27100e911903ccbee05c8b07fe3f4299e047f46553a"
    }
}

/ws/stream-otc-quotes/{account_id}

This is a WebSocket endpoint that continuously streams quotes to the client at a periodic interval.

Each generated quote is for the specific asset pair and amount. The fromQty and toQty parameters specify the amount of the 'fromAsset' or 'toAsset' to trade. Exactly one of fromQty or toQty must be specified.

Each quote sent will include the expiry time of the quote, as well as a signature that will need to be sent while accepting a quote in order to successfully complete the trade.

Request

Parameter	Type	Required	Description
account_id	string	True	Account ID in the URL path
from	string	True	Asset to buy (query parameter)
to	string	True	Asset to sell (query parameter)
fromQty	number	True	Amount of 'fromAsset' to buy (query parameter)

Response

Name	Type	Required	Description
quote	Quote	True	Quote for the trade

Quote

Name	Type	Required	Description
quoteId	string	True	Unique identifier for the quote
accountId	string	True	Account ID the quote was generated for
fromAsset	string	True	Asset to buy
toAsset	string	True	Asset to sell
fromAssetQuantity	number	True	Amount of fromAsset to buy
toAssetQuantity	number	True	Amount of toAsset to sell
expiryTime	number	True	Unix timestamp in microseconds when quote expires
signature	string	True	Signature required to execute trade with this quote

Accept quote

POST /otc/accept-quote/{account_id}

# Body
{
    "quote": {
        "quoteId": "a0743434-66c8-49b7-aca2-46c910a54cf1",
        "accountId": "a0743434-66c8-49b7-aca2-46c910a54cf1",
        "fromAsset": "BTC",
        "toAsset": "USD",
        "fromAssetQuantity": 1.25,
        "toAssetQuantity": 81436.0875,
        "expiryTime": 1733561867046245,
        "signature": "6932874cf486617239c7d27100e911903ccbee05c8b07fe3f4299e047f46553a"
    }
}

{}

POST /otc/accept-quote/{account_id}

Accepts an OTC trade quote and completes the trade.

Request

Parameter	Type	Required	Description
account_id	string	True	Account ID in the URL path
quote	Quote	True	Quote to accept for the trade

Response

If successful, returns a 200 response with an empty JSON in the response body. Otherwise, returns an error message.