Dexscreener API metrics support token activity monitoring at the trading-pair level

Token Discovery and Fixed-Pair Requests

Pair lookup suits a monitor whose target market is already known, while token lookup supports discovery of the pools associated with a token address. Direct lookup accepts chain and pair identifiers through a GET request that returns JSON. Search provides another discovery route, and the multi-token lookup supports batches within one chain. A fixed-pair monitor follows selected markets consistently; a token-wide monitor needs an explicit policy for including additional pools.

Bind each recurring monitor to an explicit pair record. Store chainId and pairAddress as its key, with base and quote identities alongside it. Pool discovery can refresh on a different schedule from metric collection. That separation prevents a changing discovery list from redirecting the monitored market. Define any token-wide total as activity across the selected pair set, and retain the contributing pairs. Broader venue coverage requires its own discovery policy; a response for one market cannot establish activity everywhere the token trades.

What Do Buy and Sell Counts Measure?

Buy and sell counts measure reported trading activity within the selected pair and time window, so they support a rule tied to that market. The txns object groups integer buys and sells counts by reporting window. Volume supplies a separate measure of trading size. Keep the window attached to both metrics so a condition compares observations covering the same period.

A buy-share calculation divides the buy count by the combined buy and sell count. It describes the proportion of counted activity classified as buys. If the combined count is zero, the share has no defined value; do not silently label it balanced buying and selling. A count-based share also differs from a share calculated from traded value, because trades can have different sizes.

Combining volume and trade-count requirements selects a narrower activity pattern than either condition alone. These aggregates do not establish how many distinct people participated or whether the activity reflects organic demand. Pair liquidity can contextualize a volume reading, although a liquidity condition measures a different aspect of the market.

Period totals also need careful comparisons across collection times. When a reporting window rolls forward, new trades enter and older trades leave. Subtracting successive totals then measures the change in the window aggregate, which can differ from activity between requests. A falling count does not mean completed trades disappeared. Avoid adding overlapping windows together or treating their difference as an itemized transaction feed.

Keep threshold crossings separate from forecasts. An activity condition describes the readings the monitor evaluated, without establishing a future price direction or identifying the traders behind the counted activity.

Nullable Fields and Observation Records

Nullable fields need explicit states in the decoder, because an absent reading and a reported zero carry different meanings for monitoring rules. The pair response represents priceUsd as a string that may be null. Parse monetary values with suitable decimal handling, preserving absence before arithmetic. Store original readings with your application’s retrieval time and validation status. A local timestamp records when collection happened; it does not certify the underlying data’s age. Keep pairCreatedAt, which describes pair creation, separate from the observation timestamp.

Request Budgets and Retry Backoff

Request scheduling needs a shared budget whenever discovery, regular polling, and retries draw on the same allowance for the monitored endpoint. Read the current request limit and any batch ceiling for the chosen endpoint in the API reference, then configure the allowance, batch size, and cadence. Calculate expected requests from actual batches per collection cycle, then reserve room for discovery and failed calls. Endpoint families can have different limits, so a profile query should not inherit the pair-query budget automatically. Batching token addresses helps within its supported chain scope. It does not grant extra request capacity or remove the endpoint’s batch ceiling.

HTTP 429 indicates that a client has sent too many requests within a given time period. If a response includes Retry-After, delay the next request accordingly. Otherwise, bounded backoff can space subsequent attempts. Cap retries and prevent scheduled cycles from launching duplicate work while an earlier request remains outstanding. Record network failures separately from successfully decoded market readings. Faster polling reduces the delay between your own observations. It cannot establish a guaranteed indexing delay or upstream update schedule.

Notification handling also needs state. Keep the last emitted condition separate from the latest reading, so repeated matches do not create a fresh notification on every successful poll.

Is This Pair Ready for a Recurring Activity Check?

The selected pair is ready for recurring checks when a matching response contains the chosen activity fields and the scheduler can accommodate its request load. A monitor combining volume with trade counts needs its chosen reporting window in both metric objects. Keep the pair identity fixed and the activity thresholds in application configuration.

• The returned chain and pair identifiers match the market saved for recurring requests.
• The selected reporting window includes volume, buys, and sells with usable values.
• The scheduler accommodates normal collection and bounded retries within the applicable request budget.
• Each observation retains raw metrics, its window, retrieval time, and validation state.
• A missing required metric suppresses the affected activity rule without replacing missing data with zero.

Enable recurring collection after these checks, and save the first valid reading as the local baseline. The next matching response can support a new observation under the same rule. Compare the same pair and reporting window, retaining both records when explaining a change. A trigger describes the configured activity condition, so its notification should include the relevant readings and their collection times.

If a later response lacks a required count, mark that observation incomplete and skip the affected trigger. Keep earlier valid readings with their original timestamps. Resume comparisons after another usable reading, while preserving the gap in the local record.

View full-size image

Aggregate Snapshots and Trade-Level Requirements

Pair-metric snapshots suit recurring activity checks and locally stored comparisons, while a monitor requiring individual trade identities needs transaction-level data for that separate task. A saved response cannot recover a trader’s address from aggregate counters. Token-profile and boost streams describe different updates; their messages do not constitute a trade feed. A custom activity notification can report a volume-and-count condition, whereas price alerts concern price movement. Snapshot polling alone cannot establish every intervening trade or the beneficial owner behind a wallet.