Articles and explainers

Coingecko API is the Simple Price Endpoint for Live Portfolio Data

Q: Can a single price request return both USD and EUR values?

Yes, one request accepts comma-separated entries in vs_currencies, so USD and EUR values return together for every matched asset. The JSON nests both quote fields beneath each coin key. Send the target currencies explicitly even though USD is the documented default, because explicit parameters make tests repeatable and prevent a client default from unexpectedly changing the payload shape.

Q: Which time zone applies to the last_updated_at value?

The last_updated_at value represents an instant as a Unix timestamp, so it has no local time zone. Convert it to UTC or the viewer's local zone only at the presentation layer. Request the field with include_last_updated_at=true, store it separately from your own fetch time, and compare both values when diagnosing an unexpectedly old price card.

Coingecko API is a REST market-data interface whose Simple Price endpoint returns current aggregated cryptocurrency prices for several coin IDs and quote currencies in one JSON response. A portfolio app sends one HTTP GET request with assets such as Bitcoin, Ethereum, and Solana, then multiplies the returned values by stored holdings. The endpoint also exposes optional market capitalization, 24-hour volume, 24-hour change, and a Unix update timestamp, making it suited to price cards, watchlists, and periodic portfolio refreshes.

Published on August 4, 2026

In short: It is a crypto market data interface that lets an app fetch live prices for multiple coin IDs in one JSON response for portfolio updates.

Choose stable coin IDs before batching assets

Coin identifiers settle whether a multi-asset request returns the intended markets. For a durable integration, select the ids parameter unless the input truly originates as a name or ticker. Simple Price accepts three lookup families: IDs, names, and symbols. If a request includes more than one family, the documented priority places IDs first, names second, and symbols third.

Bitcoin, Ethereum, and Solana use the IDs bitcoin, ethereum, and solana. Their BTC, ETH, and SOL symbols are convenient for search boxes, yet symbols are not globally unique. Tether and USD Coin also appear on multiple networks as USDT and USDC, so a bare ticker lacks chain context. The endpoint accepts a maximum of 515 IDs in one request. Symbol queries using include_tokens=all are limited to 50 symbols, while the two available token-selection modes are top and all. The /coins/list route returns the active ID, name, and symbol map in one unpaginated response.

Put authentication and rate control behind the server

API key placement is the principal security decision for this endpoint. The Coingecko API separates Demo and Pro credentials into two key families, each with its own header: x-cg-demo-api-key or x-cg-pro-api-key. Header authentication keeps credentials out of query strings, browser history, and routine access logs. A backend service should attach the header and expose a narrow response to the client.

The Demo plan permits 100 calls per minute. A successful HTTP 200 request deducts one monthly credit, so a batch of many coin IDs remains one call rather than a series of single-asset calls. Every request occupies per-minute capacity, including responses in the 4xx and 5xx classes. A 401 response indicates a missing or invalid credential, while 429 means the caller exceeded its rate limit. Retrying 401 without changing authentication repeats the same failure; a 429 handler should reduce request frequency and reuse a recent cached response.

Request only the fields your price card uses

The Simple Price response stays compact when each parameter corresponds to a visible field. vs_currencies selects the quote units, with USD documented as the default, though sending it explicitly makes application behavior easier to test. Multiple asset IDs and quote currencies use comma-separated values, and the JSON response groups the requested currency fields beneath each matched coin ID.

Four optional Boolean parameters default to false and add specific market fields:

include_market_cap adds market capitalization.
include_24hr_vol adds 24-hour trading volume.
include_24hr_change adds the 24-hour percentage change.
include_last_updated_at adds a Unix update timestamp.

The precision parameter offers full output plus every decimal setting from 0 through 18, for 20 selectable modes. Precision formats the returned currency value; it does not improve the underlying observation. A two-decimal setting suits many fiat displays, while small token values need more places. Keep last_updated_at separate from the application's fetch time because the first describes the data record and the second describes when the app received it. A null 24-hour change should remain null rather than becoming a numerical zero.

Turn one JSON response into a portfolio total

A portfolio valuation combines stored asset quantities with one price field for each matched coin ID. The arithmetic is direct, but every changing input must remain distinguishable from fixed endpoint behavior. Worked example: every balance and price in the following calculation is hypothetical and does not represent live market data.

Assume the hypothetical stored balances are 0.02 BTC, 0.50 ETH, and 10 SOL. Assume the hypothetical JSON response supplies USD prices of $100,000 for BTC, $4,000 for ETH, and $200 for SOL. The three position values are 0.02 × $100,000 = $2,000, 0.50 × $4,000 = $2,000, and 10 × $200 = $2,000. Their concrete total for this hypothetical case is $6,000. The Bitcoin balance also equals exactly 2,000,000 satoshis because one BTC contains 100,000,000 satoshis. Preserve adequate decimal precision through multiplication and addition, then round the final fiat display once. A parallel page documents Log a Buy Check.

Know what the aggregated price excludes

The aggregated market price is a reference value derived from multiple eligible trading markets rather than an executable order quote from one venue. Aggregation filters market observations before publishing a representative price. Consequently, the number returned for Bitcoin need not match the immediate buy or sell price shown by Coinbase, Kraken, or another exchange at the same moment.

An executable trade requires venue-specific information that Simple Price omits: bid, ask, order-book depth, and trading fees. A Uniswap swap also reflects pool reserves, the chosen route, the pool's fee tier, and network transaction costs. The optional 24-hour change is a percentage over that market window, not a historical series. Likewise, a candlestick requires four values - open, high, low, and close - so chart construction belongs to an OHLC or market-chart endpoint. Smart contracts that require an on-chain reference commonly use a purpose-built oracle such as Chainlink Data Feeds rather than calling a REST endpoint during execution.

Switch to contract-address pricing for chain-specific tokens

Contract-address pricing resolves assets whose symbol or name does not supply enough chain context. The Coin Price by Token Addresses route uses an asset-platform ID in its path and accepts one or more contract addresses as a query parameter. That two-part identity distinguishes deployments sharing a symbol across Ethereum, Polygon, Solana, and other supported networks.

An Ethereum ERC-20 contract address occupies 20 bytes and is commonly displayed as an 0x prefix followed by 40 hexadecimal characters, producing 42 visible characters. A Solana SPL Token uses a 32-byte mint public key instead of an Ethereum-style address. Native Bitcoin has no token contract, so BTC belongs in Simple Price under the bitcoin ID. Native Ether similarly uses ethereum, whereas Wrapped Ether, or WETH, has an ERC-20 contract address. Pairing the platform with the address also separates network-specific versions of USDT and USDC.

Fit periodic price snapshots into a production app

The Simple Price endpoint fits applications that need compact snapshots rather than continuous market streams. React dashboards, JavaScript services, Python reporting jobs, portfolio trackers, and watchlists all benefit from one batched GET request returning predictable JSON. Store the resolved coin IDs in application configuration so user-facing labels never become the database key.

Three delivery patterns address different update needs: REST uses request and response, WebSocket maintains a persistent connection for pushed data, and Webhooks deliver event-driven callbacks. Simple Price belongs to the REST pattern. Polling works well for periodic portfolio refreshes; an interface requiring continuously pushed price changes belongs on a WebSocket feed.

A production request should batch known IDs, ask only for displayed fields, include the update timestamp, and cache the successful response for the application's chosen refresh interval. Rate-limit handling belongs beside authentication on the server. This design gives the interface current aggregated market values while preserving a clear boundary between a portfolio estimate, a historical chart, and an exchange-specific execution price.

Coingecko API: common questions

Can a single price request return both USD and EUR values?

Yes, one request accepts comma-separated entries in vs_currencies, so USD and EUR values return together for every matched asset. The JSON nests both quote fields beneath each coin key. Send the target currencies explicitly even though USD is the documented default, because explicit parameters make tests repeatable and prevent a client default from unexpectedly changing the payload shape.

Is JavaScript required to call the Simple Price endpoint?

No, the endpoint only requires an HTTP client that sends a GET request and parses JSON. Python, TypeScript, JavaScript, cURL, mobile networking libraries, and serverless runtimes all work. Browser-only calls are a poor home for an API key; place the credential on a server route and return only the price fields that the interface needs.

Which time zone applies to the last_updated_at value?

The last_updated_at value represents an instant as a Unix timestamp, so it has no local time zone. Convert it to UTC or the viewer's local zone only at the presentation layer. Request the field with include_last_updated_at=true, store it separately from your own fetch time, and compare both values when diagnosing an unexpectedly old price card.

Does setting precision to 18 create a more accurate market price?

No, selecting 18 decimal places changes response formatting rather than the underlying market observation. Higher displayed precision preserves small values, while fewer places produce cleaner currency output. Choose precision for the asset and interface, retain adequate internal precision during valuation, and round the final fiat display once; extra digits do not create fresher data.

Will the Simple Price endpoint push updates without polling?

No, Simple Price follows REST request-response behavior and sends data only after a GET request. Poll it at an interval that stays within the plan's rate limit, and batch coin IDs to reduce calls. A WebSocket connection serves applications that require pushed updates, while the REST endpoint remains the simpler choice for periodic watchlists and portfolio cards.