Frequently Asked Questions
Find answers to commonly asked questions about Codex
Unable to find the answers you’re looking for? Try asking our integrated AI assistant at the top of the page, or reach out to us on Discord.
New Customers Are Asking…
Everything you need to get started can be found in our “Get Started” page. If you need further help, refer to this FAQ or reach out to us on Discord.
How can I find practical examples of Codex queries in use?
Yes, our explorer is a very powerful tool for testing Codex endpoints. It has been updated to allow multiple tabs and will save your progress when closed for future referencing.
We suggest downloading the Chrome GraphQL Network Inspector and then inspecting the queries used on Defined.fi as you navigate through the different sections of the site to find out what’s possible with the Codex API.
Websocket requests are billed per message sent by the websocket, but we offer custom plans with discounts for high usage (10m+/month). Contact us on Discord or via Email for information on custom plans.
It’s 25 per call. No limit per account.
Yes, we support short-lived tokens. You can find more information below:
Docs reference: Short-lived API Keys
SDK Example: https://github.com/Codex-Data/sdk/blob/main/examples/simple/apiKeys.ts
Overages are charged at the same rate as your subscribed plan. So if you go over 1m requests, your account is charged an additional $350, giving you up to 2m requests for that billing cycle, and so on.
Understanding Our Data & Coverage…
Pricing comes down to finding the most liquid route through pools to a bucket of stablecoins. For example, getTokenPrices uses an aggregate vlaue across all pairs based on liquidity and volume. We give each pair a weight and then use that to build a confidence score.
We index over 36m tokens (and growing rapidy) across 80+ networks, so there’s going to be a lot of unusable data mixed in. The best way to avoid this is by using filters with minimum (or maximum) values. For example, it will be higher quality data if you filter by tokens with at least 10 buys in the past 24hours, or specific amounts of volume, liquidity, trendingScore, etc.
Our Solana data begins on March 20th, 2024. Unfortunately, it is not feasible to backfill data prior to this date.
Our chart data does not explicitly display the exchange source, but you can retrieve this information using the filterTokens query and selecting the first result.
Keep in mind that exchanges are added manually. While we strive to keep our listings up to date, we index over 20,000 exhanges, so not all may be included. If you need specific exchange metadata added, feel free to reach out to our team.
There aren’t that many transactions that are dropped, but we will have multiple streams available (processed and confirmed) and you could dedupe on your end. The difference will be about 1.2s between the two.
Not currently, but it’s been a popular request so we may add it in the future. For now you can find it yourself by requesting all the daily getBars for a token and finding the highest value, though it’s not a very efficient method.
Codex uses wrapped versions of native tokens, but they are backed 1:1 so the price is the same.
The prices on our charts are the pool liquidity which is the correct pool price. Other sites use the price of the last executed transaction which isn’t correct in our opinion.
You’ll notice that our events are not the same price as the chart; the events are the executed price of that transaction and the chart is the current pool price.
We don’t have any aggregated views for tokens yet; you have to pass in a specific pair (top pair by default). This is something we want to build in the near future.
If you hover over the liquidity field on Defined.fi, you’ll get a description with a full breakdown of how the liquidity is displayed. We only display the underlying liquidity token in the pool, which usually means it will be half of other platforms. We report this amount because we believe it is somewhat deceitful to report otherwise. To get the “total” liquidity in the pool, you can simply add both sides of the pool’s liquidity.
The Codex API includes both pooled amounts in its responses if you would like to add both amounts together for your project when displaying liquidity.
We fetch data on the first trade. For social links and token images, we pull these from 10+ sources to try and compile the most comprehensive metadata we can. Some of this is on-chain and some is off-chain. We also allow updates on Defined.fi from users, which is a moderated proposal system.
If circulating supply exceeds total supply, we fall back to total supply to avoid inaccuracies. You can manually adjust this using: circulatingSupply * price
Endpoint Queries & Best Practices…
Most of our endpoints support pagination with the cursor parameter in order to retrieve additional events when necessary.
They are Unix timestamps. For example, to retrieve data for December 26th 2024 you would use “from: 1735171200 to: 1735257600”
If you’re using getTokenEvents, this looks at the top pair when filtering for events, not all pairs. To find additional data, you can use listPairsWithMetadataForToken to find the coorect pool and filter by volume.
Yes. filterPairs could be used for this.
You can subscribe to the circulatingSupply through onPairMetadataUpdated (within enhancedToken) or just check on each page load. For the most part supplies don’t really change that often though.
No, but you could use getBars and extract the closing values for similar results.
Use getDetailedPairStats for the most accurate historical data (getBars can also be useful here). getTokenPrices provides a weighted price across all pools, while individual pool prices can vary.
This parameter is for filtering MEV results and can be set to the following:
- FILTERED – MEV-related events are excluded from the data.
- UNFILTERED – Includes all events, including those related to MEV activity.
MEV transactions can significantly impact volume, liquidity, and price calculations. By using FILTERED, you get a clearer picture of organic trading activity without MEV influence. Conversely, UNFILTERED provides a full view, including arbitrage and sandwich attacks.
Yes, it’s on enhancedToken which is available for most queries.
Use the filterPairs endpoint to find the pool with the highest liquidity for a given token. Example:
filterPairs(
phrase: "0x6982508145454ce325ddbe47a25d4ec3d2311933:1"
rankings: { attribute: liquidity, direction: DESC }
)
The liquidity value represents the USD value of the base token (e.g., ETH or a stablecoin) backing the pair.
Price change metrics are available in both filterPairs and filterTokens, covering multiple timeframes.
We suggest not sorting by createdAt if you’re using phrase search. Instead, use trendingScore24 or volume which should return more meaningful results. We index well over 36m tokens so finding exactly what you want from one word phrase search is a difficult task without meaningful ranking/sorting.
WebSockets & Real-Time Data…
The limit is around 500 subscriptions per connection. Our recommendation is to use ~25 per connection, but you could have several hundred connections with 25 tokens each, for example. Growth plans have a maximum of 300 connections.
You can use the LaunchpadTokenEventType.Deployed event instead for faster updates. The difference:
Deployed: Sent immediately when token is discovered (minimal latency), includes fundamentals but may lack metadata like images.
Created: Sent after metadata is fetched (3-4s latency), includes complete token information.
For fastest results, you can set up two subscriptions and resolve the models on the frontend - use Deployed for immediate notification and Created for full metadata when available.We have plans to increase speeds (specifically for Solana) but will maintain the same Deployed vs Created flow. The naming will be improved in future versions to make this distinction clearer.
Yes, you can use the following:
onPairMetadataUpdatedfor volume updates.onHoldersUpdatedis available for enterprise users, but you can also poll theholdersendpoint.
No, but you can subscribe to up to 25 tokens at a time using onPricesUpdated, and you can make multiple subscriptions. You can also subscribe and unsubscribe from individual tokens without closing the connections.
You should be able to use shouldResubscribe for this. (https://www.apollographql.com/docs/react/data/subscriptions#options)
This usually means that you’re trying to subscribe to a websocket before receiving confirmation that you’ve successfully connected to the server. Make sure to wait for the connection_ack before subscribing.
For the token balances, it’s updated in real-time after finalization which takes about 1.8s on average.
If you are using custom code to subscribe to websockets, we advise sending a ping to keep the connection alive. Alternatively, you can use our SDK which is easier to implement, but can be less flexible.
You need to call createApiTokens then get the token from the response and send it into the Authorization header of subsequent requests:
import { Codex } from "@codex-data/sdk";
if (!process.env.API_KEY) throw new Error("Must set API_KEY");
const sdk = new Codex(process.env.API_KEY);
// Create an api token
const res = await sdk.mutations.createApiTokens({
input: { expiresIn: 3600 * 1000 },
});
const token = res.createApiTokens[0].token;
const shortLivedSdk = new Codex(`Bearer ${token}`);
shortLivedSdk.queries
.token({
input: {
address: "token_address",
networkId: 1,
},
})
.then(({ token }) => console.log(`Token: ${token.id} - ${token.symbol}`));
Webhooks & Event Monitoring…
If you’re only interested in buys, you would create a webhook for the token, only for buy events. The webhook publisher sends the full EnhancedEvent, so you don’t need to make a call to get more event data. You can also make another call to the Defined API to get more data about the token. Get started with Webhooks.
Webhooks monitor one token at a time, but there is no limit ot how many webhooks you can create.
Using “buy” events as en example: It’s 1 webhook message and 1 call per buy, so if you were processing 10k buys per day it would be 20k requests (or 600k requests per month).
There’s a hash property on all webhook messages we send, and that property is equal to:
.update(securityToken)
.update(deduplicationId)
.digest("hex")
So we take the security token you provide, and the deduplicationId of the message, and hash it together with SHA256. You should be able to do the same on your end and verify that the hash matches.
Was this page helpful?