Introduction to Astra API

Scroll down for example requests and responses.

What is it?

Astra API is a unified API for crypto markets. The API provides direct market access (DMA), i.e. it gives you fine-grained read and write access to the underlying orderbook on many different trading venues - including centralized exchanges, DEXes, and OTC desks.

Astra API takes care of data normalization, so you don't have to implement 10 different integrations for 10 different trading venues. Instead, you can just build one integration using Astra's unified data format, and use it for every trading venue.

Who is it for?

Astra API is perfect for any business that needs to build performant, robust, and easy-to-use connections to crypto markets. This includes: trading firms, individual traders, OTC desks, institutional investors, fintech companies, brokerages, neobanks, and exchanges.

Integrating with our API is easy. Any developer can get started with Astra API in minutes, using the documentation on this page.

Supported exchanges

We currently support:

• Binance
• Coinbase
• OKX
• HTX (Huobi)
• Kraken
• KuCoin

The list is growing quickly, and we plan to add support for several more exchanges and DEXes in the coming months. If there's a specific trading venue that you'd like us to prioritize, please contact us.

If you're an exchange or other trading venue, and you want us to integrate with your platform, please contact us.

Supported asset types

We currently support the following asset types for each of the above exchanges:

• Spot
• Perpetual Futures
• Expiring Futures
  • for futures, we support both USD-margined and coin-margined contracts
• Options
• (coming soon!) Leveraged Tokens
• (coming soon!) Spot Margin

Supported endpoints

See below for a detailed list of the endpoints we support:

• Public market data via WebSocket
• Public market data via REST
• Private trading data via REST

How it works

If you are using Astra API for fetching real-time market data, all you need to get started is an API key, which you can get by following the steps below.

In order to use Astra API for order management, execution, or position management, you need to first do the following for each exchange you wish to trade on:

1. Create an account
2. Perform KYC verification if applicable
   • This is common for centralized exchanges, but typically not for DEXes
3. Deposit funds onto the exchange
4. Get approved for each asset type you want to trade
   • Many exchanges will ask you to go through a quiz or signup process on their website in order to trade futures, options, and other margin products

You will then export your API keys from each exchange to use them with Astra API. More details on how to do this coming soon, once we add support for private exchange endpoints.

If you would like to self-host Astra API on your own servers, see below.

Getting Started

1. Create an account

First, create an account with us here: https://terminal.astra-api.dev/settings/apikeys. You can use your Astra account to access all of our products and services.

2. Create an API key

Navigate to https://terminal.astra-api.dev/settings/apikeys and create an API key. The key will only be displayed once upon creation, so make sure you save it.

3. Send your first request

Endpoints

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

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

Authentication

All requests to Astra API need to be authenticated

{
    "x-astra-api-key": "Bearer kadjfasfl.KjUBAhdIafaDFSCsajfaIowSADxkaw"
}

You can authenticate by specifying a header named x-astra-api-key with the value Bearer {KEY}, where you replace "KEY" with the value of your API key. For example, if the API key you created in the previous step was kadjfasfl.KjUBAhdIafaDFSCsajfaIowSADxkaw, you would include the header displayed to the right.

Requests to the public market data endpoints do not require any additional authentication beyond your Astra API key. Private endpoints also require you to provide your exchange API keys for the specific exchange(s) you are trading on. More info on how to do this will be released once we enable support for private endpoints (currently in development).

Send a request

Sample Request

curl --location 'http://prod.astra-api.dev/orderbook?market=BINANCE-SPOT-BTC-USDT' \
--header 'x-astra-api-key: Bearer {ASTRA_API_KEY}'

Sample Response

{
    "bids": [
        {"price": 51485.41, "quantity": 4.10646},
        {"price": 51485.39, "quantity": 0.00975},
        {"price": 51485.38, "quantity": 0.00975},
    ],
    "asks": [
        {"price": 51485.42, "quantity": 2.21005},
        {"price": 51485.59, "quantity": 0.77624},
        {"price": 51485.89, "quantity": 0.38811},
    ]
}

Use your favorite HTTP client to send a market data request. Here's an example curl command you can use:

Replace {ASTRA_API_KEY} with the API key that you just generated. You should receive a response with a current snapshot of the orderbook for that market!

Public REST API

Endpoint: https://prod.astra-api.dev

Authentication

Remember to specify an authentication header with your API key, as described above. Otherwise, your requests will fail.

Get Markets

Sample Request

GET /markets?exchange=BINANCE

Sample Response

[
    {
        "symbol": "BINANCE-SPOT-ETH-USDT",
        "assetType": "SPOT",
        "baseAsset": "ETH",
        "quoteAsset": "USDT"
    },
    {
        "symbol": "BINANCE-PERP-BTC-USDT",
        "assetType": "PERP",
        "baseAsset": "BTC",
        "quoteAsset": "USDT",
        "marginAsset": "USDT"
    },
    {
        "symbol": "BINANCE-PERP-BTC-USD-COINM",
        "assetType": "PERP",
        "baseAsset": "BTC",
        "quoteAsset": "USD",
        "marginAsset": "BTC"
    },
    {
        "symbol": "BINANCE-FUT-BTC-USDT-210625",
        "baseAsset": "BTC",
        "quoteAsset": "USDT",
        "marginAsset": "USDT"
    }
]

GET /markets

Returns all markets on the specified exchange that are supported by Astra, along with their associated metadata.

You can see the list of asset types we currently support here. We're working on expanding our coverage to all tradeable markets.

Request

Response

Get Orderbook

Sample Request

GET /orderbook?market=BINANCE-SPOT-ETH-USDT

Sample Response

{
  "bids": [
    {
      "price": 1798.00,
      "quantity": 1.5,
    },
    {
      "price": 1797.01,
      "quantity": 5.0,
    }
  ],
  "asks": [
    {
      "price": 1798.00,
      "quantity": 1,
    },
    {
      "price": 1797.00,
      "quantity": 10.0,
    }
  ]
}

GET /orderbook

Returns a snapshot of the current L2 orderbook for the specified market. Bids are sorted in descending order of price, and asks are sorted in ascending order. The quantity at each price level corresponds to the aggregate of all open orders at that price.

Request

Response

WebSocket API

You can use the WebSocket API to stream real-time market data.

Endpoint: wss://prod.astra-api.dev/ws

Authentication

Remember to specify an authentication header with your API key, as described above. Otherwise, your requests will fail.

Subscribing

You can have one active market data subscription per WebSocket connection. A "subscription" consists of a combination of a market and the data type you are subscribing to.

wss://prod.astra-api.dev/ws?market=BINANCE-PERP-BTC-USDT&dataType=ORDERBOOK

These are specified as query parameters in the initial connection request, as shown:

Request

Orderbook Channel

Sample Request

wss://prod.astra-api.dev/ws?market=BINANCE-PERP-BTC-USDT&dataType=ORDERBOOK

Sample Data Message

{
    "updateId": 37828320367,
    "bids": [
        {
            "price": 30708.01,
            "size": 1.26141
        },
        {
            "price": 30707.97,
            "size": 0.00571
        }
    ],
    "asks": [
        {
            "price": 30708.02,
            "size": 12.005
        },
        {
            "price": 30708.1,
            "size": 0.08388
        }
    ]
}

Streams L2 orderbook updates from the specified market.

For each exchange, we've used whichever endpoint returns the most fine-grained orderbook updates with the lowest latency. For some exchanges, this is one update per tick, and for some exchanges, batched updates are the best that is available. Contact us for more information about how this is implemented under the hood.

Message

Trades Channel

Sample Request

wss://prod.astra-api.dev/ws?market=BINANCE-PERP-BTC-USDT&dataType=TRADE

Sample Data Message

{
    "trades": [
        {
            "price": 47104.0,
            "quantity": 0.003,
            "side": "SELL",
            "time": 1707527023484
        },
        {
            "price": 47100.1,
            "quantity": 0.0015,
            "side": "BUY",
            "time": 1707527025010
        }
    ]
}

Streams trade updates from the specified market.

For each exchange, we've used whichever endpoint returns the most fine-grained trade updates with the lowest latency. For some exchanges, this is one update per trade, and for some exchanges, batched updates are the best that is available. Contact us for more information about how this is implemented under the hood.

Message

Private REST API

Get Orders

GET /orders

Fetches the user's open orders for the specified market.

Get Fills

GET /fills

Fetches the user's fills for the specified market.

Get Balances

GET /balances

Fetches the user's balances of all assets on the exchange. This includes deposits, collateral and open positions.

Get Positions

GET /positions

Fetches the user's positions on the specified exchange.

Place Order

POST /orders

Place and order on the specified exchange and market.

Cancel Order

DELETE /orders

Cancels the specified order.

Schema

Exchange

Represents a trading venue supported by Astra. The full list of currently supported exchanges is:

Market

Sample Data

Represents a particular market on a particular trading venue.

# Format for spot and perpetual futures markets:
{EXCHANGE}-{ASSET_TYPE}-{BASE_ASSET}-{QUOTE_ASSET}-?{DISAMBIGUATOR}

# Format for expiring futures markets:
{EXCHANGE}-{ASSET_TYPE}-{BASE_ASSET}-{QUOTE_ASSET}-{EXPIRY_SYMBOL}-?{DISAMBIGUATOR}

# Format for options markets:
{EXCHANGE}-{ASSET_TYPE}-{BASE_ASSET}-{QUOTE_ASSET}-{EXPIRY_SYMBOL}-{STRIKE_SYMBOL}-?{DISAMBIGUATOR}

Astra has developed a custom naming scheme to represent crypto markets across many diverse trading venues. Every tradeable market is assigned a "market symbol", which is a string that serves as the globally unique identifier for that market. The market symbol is also human-readable, and contains information about the exchange, base asset, quote asset, and metadata of that market.

On the right, you can see the format of market symbols for four popular asset types: spot, perpetual futures, expiring futures, and options.

"Disambiguator" is an optional parameter which is used to differentiate markets that are the same on all other parameters. For example, many exchanges have two types of futures contracts which differ in their margin behavior: those margined in USD or stablecoins (usually called "USD-margined" or "USD-M"), and those margined in the underlying base asset of the market (usually called "coin-margined" or "Coin-M"). To differentiate these, we use the "-COINM" disambiguator for coin-margined markets, and no disambiguator for USD-margined markets, which are more popular.

Here are some examples of various market symbols, along with descriptions of the markets they map to:

MarketMetadata

Sample Data

{
    "symbol": "BINANCE-PERP-BTC-USD-COINM",
    "assetType": "PERP",
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "marginAsset": "BTC"
}

Metadata associated with a particular market.

AssetType

Represents the type of asset that a particular market is for. We currently support the following asset types:

AbstractToken

Represents an abstract "token" such as BTC, ETH, USD, USDT, etc. This will usually refer to a fungible blockchain token, but could potentially refer to other token-like assets such as equities, etc.

This representation is agnostic to implementation details such as the network and token standard, such as ERC-20 or TRC-20 or SPL.

It is also agnostic to any particular exchange's symbology. For example, Bitcoin from both Binance and BitMEX will map to an AbstractToken of BTC, even though Binance refers to Bitcoin as 'BTC' and BitMEX refers to Bitcoin as 'XBT'.

NOTE: We do incorporate the exchange's symbology into our market symbols! So our symbol for the BTC/USDT spot market on Binance is BINANCE_SPOT_BTC_USDT, while our symbol for the same market on BitMEX (once we enable support for BitMEX) will be BITMEX_SPOT_XBT_USD - because BitMEX uses 'XBT' to refer to Bitcoin and uses 'USD' rather than 'USDT' as the quote asset for this market. However, when you fetch the MarketMetadata for both these markets using our /markets endpoint, they will both have a baseAsset of BTC.

Data Type

Bid

Sample Data

{
    "price": 27879.5,
    "quantity": 1.5,
}

Represents the aggregate of all buy orders on a particular market for a given price level.

Ask

Sample Data

{
    "price": 27500.00,
    "quantity": 1,
}

Represents the aggregate of all sell orders on a particular market for a given price level.

Trade

Sample Data

{
    "exchangeMarket": {
        "exchange": "BINANCE",
        "market": {
            "baseAsset": {
                "type": "SPOT",
                "asset": "BTC"
            },
            "quoteAsset": "USDT"
        }
    },
    "price": 30199.49,
    "quantity": 0.0032,
    "side": "SELL"
}

Astra represents a trade through Trade on a specific market on an exchange.

Exchange Market

Side

Self hosting

What is it?

Astra API is available in two modes: managed and self-hosted.

With managed hosting, we run all the infrastructure behind the scenes to give you fast, robust market access.

With self-hosting, we provide you with a lightweight proxy agent that you run on your own servers. Your business software can then interact directly with each exchange via our proxy.

To get started, create an account with us and create and Astra API key. If you are using our API only to access public market data, then this is all you need.

If you are placing/cancelling orders or fetching your private user data, you will need to bring your own exchange accounts and API keys. Once you have set up accounts on an exchange, you can export your API keys and use that with the Astra API.

How to Self-Host?

For self-hosting, follow these steps:

1. Install Docker: Ensure Docker is installed on your server. If not, visit Docker's official website for instructions.

docker run -d --platform linux/amd64 -p 8080:8080 -p 9090:9090 --env ASTRA_API_KEY=$ASTRA_API_KEY --name astra-gateway -t docker.io/astraimages/gateway:v0.0.1-alpha

1. Obtain your API key Refer above for how to create an account and an Astra API key. Your API key is crucial for authentication and ensuring secure communication with the Astra API.

2. Run the astra-gateway proxy Execute the following command in a shell on your server. Replace $ASTRA_API_KEY in the command with your actual Astra API key.

Data Privacy

For users of managed hosting, your data is encrypted in transit via HTTPS, and we never read any credentials that you transmit via our API. We have a strict no-logging policy for sensitive user data, which means that any credentials get destroyed as soon as they are used, and are never written to disk.

For users of self-hosting, you fully own your data. Your data, keys, and other credentials never leave your servers. Astra's proxy agent is self-contained, and only communicates with our servers to authenticate you and make sure you have a valid Astra API key.