Alert

100% of Nomics Was Created With Our Free Crypto API.  Free Instant Access 

Nomics Cryptocurrency & Bitcoin API (1.0.0)

Download OpenAPI specification:Download

Introduction

Welcome to the Nomics Cryptocurrency & Bitcoin API. To sign up for an API key please go here.

nomics.com is built entirely with the Nomics API. Everything we've done on nomics.com you can do with our API. There are no internal API endpoints.

If you need support, reach out to use at our forums.

General

API Server URL

The Nomics API runs at https://api.nomics.com/v1. All requests should be prefixed by the server URL.

JSON and CSV Support

By default, all endpoints serve data as JSON. However, by passing format=csv in the URL, an endpoint will return CSV data. This can be used in Google Sheets via the IMPORTDATA function.

CSV responses will not contain a header row, this is so that data can be easily concatenated from multiple requests. The fields will be rendered in the same order as the JSON fields. See the endpoint's documentation for an example.

Errors

The Nomics API uses standard HTTP status codes to indicate success or failure. 200 represents success, 4xx represents a user error (such as a problem with your key), and 5xx represents a problem with our API.

Versioning

We follow Semantic Versioning. That means our API is versioned as Major.Minor.Patch. For example, Version 1.2.3 has major version 1, minor version 2, and patch version 3.

Major version changes indicate that we have altered the API significantly and it is no longer compatible with a previous version. Major versions are also used as the API URL prefix.

When we update the major version, we will not remove the previous version without notice to API customers and a deprecation period to allow everyone to smoothly update to the new version.

Minor version changes indicate that we have added new functionality without breaking any existing functionality. An API client is compatible with future minor versions. Note that a minor version update may add a new field to an existing API endpoint's response. Your API client must ignore fields it does not understand in order to be compatible with future minor versions.

Patch version changes indicate we fixed a bug or security vulnerability. Patch versions don't add new functionality.

Cross Origin Resource Sharing (CORS)

This API supports Cross Origin Resource Sharing, which allows you to make API requests directly from your user's browser.

To use CORS, you must provide Nomics with the domains on which your application will run so that we can whitelist them for CORS access.

Requests from localhost, 127.0.0.1, and 0.0.0.0 will always succeed to aid in development.

Demo Application

A demo application using the Nomics API, CORS, and React is available on Glitch.com. This can help you get started using the Nomics API. Keep in mind it uses the demo key, which is rotated frequently. You should get your own API key before deploying an app to production. Check it out:

Demo Spreadsheet

Here is a demo of using the Nomics API with Google Sheets.

Open in Google Sheets to Copy and Edit

SDKs and Libraries

Community Submissions

We love watching developers explore new use-cases with our API. Whether you're tinkering on a small side project or building an open-source resource, please share what you're up to in our forums.

Authentication

Key

You must include your API Key as a query parameter in every request you make.

For example:

https://api.nomics.com/v1/markets?key=your-api-key-goes-here

The key used in the examples on this page is changed regularly and is intended only as a demo. Get your free Nomics API key here

Security scheme type: API Key
query parameter name: key

Currencies

Currencies Ticker

Price, volume, market cap, and rank for all currencies across 1 hour, 1 day, 7 day, 30 day, 365 day, and year to date intervals. Current prices are updated every 10 seconds.

Authorizations:
query Parameters
ids
string
Example: "BTC,ETH,XRP"

Comma separated list of Nomics Currency IDs to filter result rows

interval
string
Enum:"1h" "1d" "7d" "30d" "365d" "ytd"
Example: "1d,30d"

Comma separated time interval of the ticker(s). Default is 1d,7d,30d,365d,ytd.

quote-currency
string
Deprecated
Example: "EUR"

Currency to quote ticker price, market cap, and volume values. Must be a valid currency from Exchange Rates. Default is USD.

convert
string
Example: "EUR"

Currency to quote ticker price, market cap, and volume values. May be a Fiat Currency or Cryptocurrency. Default is USD.

Responses

200

Price, volume, market cap, and rank for all currencies

get /currencies/ticker
API Server
https://api.nomics.com/v1/currencies/ticker

Request samples

Copy
curl "https://api.nomics.com/v1/currencies/ticker?key=2018-09-demo-dont-deploy-b69315e440beb145&ids=BTC,ETH,XRP&interval=1d,30d&convert=EUR"

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Currencies Metadata

The currencies endpoint returns all the currencies and their metadata that Nomics supports.

Authorizations:
query Parameters
ids
string
Example: "BTC,ETH,XRP"

Comma separated list of Nomics Currency IDs to filter result rows

attributes
string
Example: "id,name,logo_url"

Comma separated list of currency attributes to filter result columns

Responses

200

A list of Nomics Currencies

401

Authentication information is missing or invalid

get /currencies
API Server
https://api.nomics.com/v1/currencies

Request samples

Copy
curl "https://api.nomics.com/v1/currencies?key=2018-09-demo-dont-deploy-b69315e440beb145&ids=BTC,ETH,XRP&attributes=id,name,logo_url"

Response samples

Copy
Expand all Collapse all
[]

Currencies Sparkline

The currencies sparkline endpoint returns prices for all currencies within a customizable time interval suitable for sparkline charts.

Note the timestamps and prices are built off of OHLCV candles using the close price. This means that the timestamp represents the start of the candle, and the price is the close price of that candle. This means the response's final timestamp and price value are always as current as possible, but also that the price is effectively "off" by one candle. This endpoint is designed to serve as a convenient way to render sparklines, if you need exactly aligned times and prices you can use the Aggregated OHLCV Candles endpoint.

Authorizations:
query Parameters
start
required
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped)

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

Currency performance over time for all currencies over the requested time period.

401

Authentication information is missing or invalid

get /currencies/sparkline
API Server
https://api.nomics.com/v1/currencies/sparkline

Request samples

Copy
curl "https://api.nomics.com/v1/currencies/sparkline?key=2018-09-demo-dont-deploy-b69315e440beb145&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Markets

Markets

The markets endpoint returns information on the exchanges and markets that Nomics supports, in addition to the Nomics currency identifiers for the base and quote currency.

Authorizations:
query Parameters
exchange
string
Example: "binance"

Nomics Exchange ID to filter by

base
string
Example: "BTC,ETH,LTC,XMR"

Comma separated list of base currencies to filter by

quote
string
Example: "BTC,ETH,BNB"

Comma separated list of quote currencies to filter by

Responses

200

A list of markets

401

Authentication information is missing or invalid

get /markets
API Server
https://api.nomics.com/v1/markets

Request samples

Copy
curl "https://api.nomics.com/v1/markets?key=2018-09-demo-dont-deploy-b69315e440beb145&exchange=binance&base=BTC,ETH,LTC,XMR&quote=BTC,ETH,BNB"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Market Cap History

MarketCap History is the total market cap for all cryptoassets at intervals between the requested time period.

Authorizations:
query Parameters
start
required
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped)

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

Performance over time for the entire market.

401

Authentication information is missing or invalid

get /market-cap/history
API Server
https://api.nomics.com/v1/market-cap/history

Request samples

Copy
curl "https://api.nomics.com/v1/market-cap/history?key=2018-09-demo-dont-deploy-b69315e440beb145&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Volume

Global Volume History

Volume History is the total volume for all cryptoassets in USD at intervals between the requested time period.

Authorizations:
query Parameters
start
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped)

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

Volume over time for all currencies

401

Authentication information is missing or invalid

get /volume/history
API Server
https://api.nomics.com/v1/volume/history

Request samples

Copy
curl "https://api.nomics.com/v1/volume/history?key=2018-09-demo-dont-deploy-b69315e440beb145&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Exchange Rates

Exchange Rates

The exchange rates endpoint returns the current exchange rates used by Nomics to convert prices from markets into USD. This contains Fiat currencies as well as a BTC and ETH quote prices. This endpoint helps normalize data across markets as well as to provide localization for users.

Currently, this endpoint does not support historical data, but this feature is planned.

Authorizations:

Responses

200

List of exchange rates into USD

401

Authentication information is missing or invalid

get /exchange-rates
API Server
https://api.nomics.com/v1/exchange-rates

Request samples

Copy
curl "https://api.nomics.com/v1/exchange-rates?key=2018-09-demo-dont-deploy-b69315e440beb145"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Exchange Rates History

Exchange rates for every point in a time range. This endpoint can be used with other interval endpoints to convert values into a desired quote currency.

The currency parameter must be a Nomics Quote Currency, to get all Nomics Quote Currencies, use the /exchange-rates endpoint for all current rates.

Authorizations:
query Parameters
currency
required
string
Example: "BTC"

Currency ID

start
required
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped)

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

Exchange rates for every point in a time range

401

Authentication information is missing or invalid

get /exchange-rates/history
API Server
https://api.nomics.com/v1/exchange-rates/history

Request samples

Copy
curl "https://api.nomics.com/v1/exchange-rates/history?key=2018-09-demo-dont-deploy-b69315e440beb145&currency=BTC&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Exchange Rates Interval

Exchange rates to convert from USD over a time interval. This endpoint can be used with other interval endpoints to convert values into a desired quote currency.

Authorizations:
query Parameters
start
required
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped)

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

List of exchange rates open and close information

401

Authentication information is missing or invalid

get /exchange-rates/interval
API Server
https://api.nomics.com/v1/exchange-rates/interval

Request samples

Copy
curl "https://api.nomics.com/v1/exchange-rates/interval?key=2018-09-demo-dont-deploy-b69315e440beb145&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Currencies*

Supplies Interval

!! This API endpoint is only available to customers of our paid API plans. Please go here to learn more.

Open and close supply information for all currencies between a customizable time interval.

Authorizations:
query Parameters
start
required
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped)

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

Open and close supply information

401

Authentication information is missing or invalid

get /supplies/interval
API Server
https://api.nomics.com/v1/supplies/interval

Request samples

Copy
curl "https://api.nomics.com/v1/supplies/interval?key=2018-09-demo-dont-deploy-b69315e440beb145&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Exchanges*

Exchanges Ticker

The Exchanges Ticker provides high level information about the exchanges integrated with Nomics. It provides a limited amount of metadata, the type of integration, the time range of available data, pairs, and interval information about the volume and, where applicable, the number of trades.

Authorizations:
query Parameters
ids
string
Example: "binance,gdax"

Comma separated list of Nomics Exchange IDs to filter result rows

interval
string
Enum:"1h" "1d" "7d" "30d" "365d" "ytd"
Example: "1d,30d"

Comma separated time interval of the ticker(s). Default is 1d.

Responses

200

Metadata and interval data for exchanges

401

Authentication information is missing or invalid

get /exchanges/ticker
API Server
https://api.nomics.com/v1/exchanges/ticker

Request samples

Copy
curl "https://api.nomics.com/v1/exchanges/ticker?key=2018-09-demo-dont-deploy-b69315e440beb145&ids=binance,gdax&interval=1d,30d"

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Exchanges Metadata

The exchanges endpoint returns all the exchanges and their metadata that Nomics supports.

Authorizations:
query Parameters
ids
string
Example: "binance,idex,bittrex"

Comma separated list of Nomics Exchange IDs to filter result rows

attributes
string
Example: "id,name,transparency_grade"

Comma separated list of exchange attributes to filter result columns

Responses

200

A list of Nomics Exchanges

401

Authentication information is missing or invalid

get /exchanges
API Server
https://api.nomics.com/v1/exchanges

Request samples

Copy
curl "https://api.nomics.com/v1/exchanges?key=2018-09-demo-dont-deploy-b69315e440beb145&ids=binance,idex,bittrex&attributes=id,name,transparency_grade"

Response samples

Copy
Expand all Collapse all
[]

Markets*

Market Prices

!! This API endpoint is only available to customers of our paid API plans. Please go here to learn more.

The market prices endpoint returns prices in USD for the last trade in each market with the given base currency. These prices only include markets with quote currencies that are used as part of our Pricing Methodology (fiat, BTC, and ETH) to convert to USD.

Authorizations:
query Parameters
currency
required
string
Example: "BTC"

Nomics Currency ID of the desired base currency

Responses

200

A list of markets with their price

401

Authentication information is missing or invalid

get /markets/prices
API Server
https://api.nomics.com/v1/markets/prices

Request samples

Copy
curl "https://api.nomics.com/v1/markets/prices?key=2018-09-demo-dont-deploy-b69315e440beb145&currency=BTC"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Market Interval

!! This API endpoint is only available to customers of our paid API plans. Please go here to learn more.

The market interval endpoint returns a summary of information about all markets based in a given currency over a configurable time interval.

Authorizations:
query Parameters
currency
required
string
Example: "BTC"

Nomics Currency ID to query information for

hours
integer [ 1 .. 8760 ]
Default: 1

Number of hours back to calculate data

start
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped). If not provided, it is computed using the hours parameter.

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

A list of markets with price and volume information for a currency

401

Authentication information is missing or invalid

get /markets/interval
API Server
https://api.nomics.com/v1/markets/interval

Request samples

Copy
curl "https://api.nomics.com/v1/markets/interval?key=2018-09-demo-dont-deploy-b69315e440beb145&currency=BTC&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Exchange Market Prices

!! This API endpoint is only available to customers of our paid API plans. Please go here to learn more.

The exchange market prices endpoint returns prices for the last trade in each market

Authorizations:
query Parameters
currency
string
Example: "BTC"

Nomics Currency ID to filter by. If present, only markets with this currency as the base or quote will be returned.

exchange
string
Example: "binance"

Nomics Exchange ID to filter by. If present, only markets on this exchange will be returned

Responses

200

A list of markets with their prices

401

Authentication information is missing or invalid

get /exchange-markets/prices
API Server
https://api.nomics.com/v1/exchange-markets/prices

Request samples

Copy
curl "https://api.nomics.com/v1/exchange-markets/prices?key=2018-09-demo-dont-deploy-b69315e440beb145&currency=BTC&exchange=binance"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Exchange Market Interval

!! This API endpoint is only available to customers of our paid API plans. Please go here to learn more.

The exchange market interval endpoint returns a summary of information about all markets over a configurable time interval in their native values.

Authorizations:
query Parameters
currency
string
Example: "BTC"

Nomics Currency ID to filter by. If present, only markets with this currency as the base or quote will be returned.

exchange
string

Nomics Exchange ID to filter by. If present, only markets on this exchange will be returned

start
required
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped).

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

A list of markets with price and volume information for a currency

401

Authentication information is missing or invalid

get /exchange-markets/interval
API Server
https://api.nomics.com/v1/exchange-markets/interval

Request samples

Copy
curl "https://api.nomics.com/v1/exchange-markets/interval?key=2018-09-demo-dont-deploy-b69315e440beb145&currency=BTC&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {
    }
]

Candles*

What are OHLCV Candles?

OHLCV Candles is an abbreviation of "Open, High, Low, Close, and Volume Candlestick Data". Each "Candle" represents a point in time of an asset's price history.

For example, take the following pricing data:

Month High Open Close Low
January $70 $20 $50 $15
February $66 $50 $45 $25
March $80 $45 $62 $30
April $95 $62 $85 $50
May $90 $85 $70 $60

A candlestick chart of this data in Google Sheets looks like this:

Candlestick Chart

The lines extending from the boxes are called "wicks" and they represent the high and low for that time period. The top and bottom of the boxes represent the open and close. Different visualizations of candles have different ways of conveying which of the top and bottom of the boxes are the open and close. In this case, with Google Sheets, candles that close higher than they open are solid colors, while candles that close lower than they open are transparent.

How are Candles Built?

At Nomics, we have three methods of building candles:

  1. Building candles from raw, gapless trade execution data (sometimes called "tick data")
  2. Ingesting candles directly from exchanges, and building intermediate sizes
  3. Ingesting 24 hour tickers from exchanges, and extrapolating estimated candles

The first method, trades, is greatly preferred as it yields the most accurate and trustworthy data. The second method, candles, is also very accurate, but without the underlying trade data, it is not as transparent. The third method, tickers, is the lowest quality source and should only be used as an estimate of pricing activity.

Why don't candles show up right away?

You may notice that candles don't show up immediately after they start. For example, at 12:01am, you may not see a daily, hourly, or even a minute candle for 12:00am yet. This is because several steps need to occur in order to build a candle:

  1. Trades must be executed on an exchange. If there are no trades after 12:00am for a market or currency, there is simply no data to represent.
  2. Trades must be ingested into Nomics. We ingest data as fast as possible, but due to exchange rate limits and limitations on the speed of data across the internet, there is always a delay between a trade being executed and when it arrives in the Nomics database.
  3. An Exchange Candle must be built. Once we have the trade in our database, we then aggregate all trades within the candle's time range in order to build and store the candle.
  4. An Aggregate Candle must be built. After an Exchange Candle is built (which represents a single market on a single exchange) we must build an Aggregated Candle (which represents an asset across all markets and exchanges)

Every step in this pipeline takes time to compute, which means that it may be seconds, or even minutes before a trade is fully represented by all candle types in our data set.

For more information about update frequencies, see the descriptions of our candle types below.

Aggregated OHLCV Candles

!! This API endpoint is only available to customers of our paid API plans. Please go here to learn more.

The candles endpoint returns aggregated open, high, low, close, and volume information for Nomics currencies. When asking for candles, a currency is provided as a parameter. Nomics aggregates all markets where the given currency is the base currency and the quote currency is a fiat currency, BTC, or ETH and returns all values in USD.

Candles are aggregated across all markets for the base currencies, which necessitates converting to a common quote currency. Nomics converts all markets into USD in order to aggregated candles.

Candles have the following history based on size:

  • 1d: From inception updated every 15 minutes
  • 1h: Rolling 30 days updated every 5 minutes
Authorizations:
query Parameters
interval
required
string
Enum:"1d" "1h"
Example: "1d"

Time interval of the candle

currency
required
string
Example: "BTC"

Currency ID

start
string
Example: "2018-04-14T00%3A00%3A00Z"

Start time of the interval in RFC3339 (URI escaped). If not provided, starts from first candle.

end
string
Example: "2018-05-14T00%3A00%3A00Z"

End time of the interval in RFC3339 (URI escaped). If not provided, the current time is used.

Responses

200

A list of candles

401

Authentication information is missing or invalid

get /candles
API Server
https://api.nomics.com/v1/candles

Request samples

Copy
curl "https://api.nomics.com/v1/candles?key=2018-09-demo-dont-deploy-b69315e440beb145&interval=1d&currency=BTC&start=2018-04-14T00%3A00%3A00Z&end=2018-05-14T00%3A00%3A00Z"

Response samples

Copy
Expand all Collapse all
[
  • {