Dexscreener API Token Lookup and Pool Data

Token Input and Pool Identity

A token-to-pool lookup starts with the chain identifier and token address that belong to the same blockchain. A token address identifies an asset; a pair address identifies a particular pool.

Request Inputs

The token-pairs v1 resource accepts chainId and tokenAddress for a token’s associated pools. Keep the address intact and retain its chain throughout storage and display. A symbol cannot replace these identifiers. The response concerns the service’s indexed markets, so a lookup does not establish that every possible pool exists in the returned collection. An empty collection supplies no matching market record; it does not establish that the token itself cannot exist.

Matched Pool Records

A completed HTTP request supplies a response; an application needs matching pool records before it can present a market. Match the requested address against the returned baseToken and quoteToken addresses. Retain the chain, exchange identifier, and pairAddress alongside the measurements. Those identifiers let the application update the appropriate pool record from later responses. If essential identity fields are missing, keep that record outside automatic matching. Distinct pool addresses remain separate records, even when their token symbols match.

Can Pool Data Predict a Swap’s Final Output?

Pool data cannot determine a swap’s final output because the requested trade introduces conditions beyond a market snapshot. A trade quote needs the amount being exchanged and the route that will execute it. Exchange fees and market changes can alter the amount received. Reported liquidity also does not establish whether a particular token transfer will succeed. These GET resources retrieve market information; they do not submit a swap or authorize token spending.

Multiplying the priced token’s quantity by its USD unit price gives an indicative valuation. That arithmetic excludes trade-size effects and execution fees.

How Should a Client Handle Null Market Values?

A client should preserve null and missing fields as unavailable data, then decide whether the remaining record serves its task.

Unavailable Measurements

The pair schema permits priceUsd to be null. The liquidity object can also be null, so checking the object comes before reading its USD measurement. An absent key needs an unavailable state too. Substituting zero creates a false measurement. A display may retain an identifiable pool while leaving its price blank. A filter that requires a liquidity measurement cannot classify that pool until the relevant value exists.

Response Containers and Numeric Types

The token-pool and token-batch resources return arrays, while pair-address and search resources place records inside a pairs property. An endpoint-specific parser can convert those containers into a common internal collection. The priceUsd and priceNative fields use strings, so usable values need deliberate conversion before arithmetic. Keep failed requests separate from successfully parsed empty collections. Missing measurements, an unexpected response shape, and an HTTP failure require different handling because they describe different problems.

A Hypothetical Preview Before Any Swap

A hypothetical application requires both USD price and USD liquidity before including a pool in its liquidity-filtered comparison. Assume a reader supplies a valid token address and matching chain identifier. The lookup returns a matching pool with a usable USD price and null liquidity. The reader wants to inspect the market before authorizing a trade, so a read-only token-pool request fits the task.

Open full-size image

The returned chain and token addresses associate the record with the requested token. Null liquidity fails the application’s comparison rule, so the pool stays outside its ranked results. The preview retains the available price and pool identity, with liquidity marked as unavailable. No trade authorization forms part of this retrieval. If a later response supplies usable liquidity, the application can reconsider the same pool under its existing rule.

Base and Quote Sides in Market Measurements

Price interpretation starts with the token that a measurement describes, while activity comparisons need matching observation windows. The base and quote token objects distinguish the sides of a pair. Read both token identities before assigning a pool measurement to the queried token. Keep each measurement attached to the side that it describes. Volume, transaction counts, and price changes belong to their respective time windows. Comparing unmatched windows can make unrelated activity look comparable. These distinctions also matter when the data feeds price alerts or a monitor for new pairs.

Search, Pair Refreshes, and Token Batches

The useful lookup resource changes with the identifier available and the scope of the request. Search finds pairs matching a query. A token lookup retrieves associated pools, while a pair-address lookup targets a known market. Saving a pool’s chain and pair address preserves that selection for later requests. Searching again by symbol can return a different collection and should not silently replace the selected pool.

The tokens v1 resource accepts comma-separated token addresses within a single chain. Batches must respect the resource’s address cap. Group the returned pool records by their token identities, without assuming that a result occupies the same position as its input. A token can have several associated pools, so the address count does not define the response’s record count.

Repeated GET requests refresh the application’s observations. A scheduler should respect the applicable request limit and avoid bursts from overlapping refresh jobs. Keep request limits and batch size configurable because service policies can change. Store retrieval time separately from any market timestamp; a local download time records when the application received data.

A cached response can keep a display populated during a refresh. Show its age and retain the refresh failure when a newer request fails. A changed chain, token, or pair requires a corresponding change in the cache key. Older data for one market must not become the displayed observation for another.