> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Queries

> Queries are one-time GraphQL requests over HTTP and the basic building block of the Codex API. Learn how they work and when to use them.

## What is a Query?

A query is a one-time request for data. You send a GraphQL query to the Codex API over HTTP, and you get back a response with the data you asked for. Queries are the standard way to fetch token prices, wallet stats, historical bars, holder lists, and everything else in the API.

**Every query you run counts as 1 request** against your plan's monthly limit.

> [!TIP]
>
> Not sure whether to use a query or a subscription? See [Queries vs Subscriptions](https://docs.codex.io/extra/queries-vs-subscriptions.md) for a side-by-side comparison and endpoint mapping.

## When to Use Queries

* **Fetching current state** — token prices, metadata, pair stats, wallet balances
* **Historical data** — OHLCV bars, trade events, wallet charts
* **Paginated lists** — filtering tokens, wallets, pairs, or events with cursor-based pagination
* **One-time lookups** — loading a page, responding to a user action, backfilling data

If you need data pushed to you continuously in real-time (e.g. live price feeds or streaming trades), use [Subscriptions](https://docs.codex.io/concepts/subscriptions.md) instead.

## How It Works

Send a `POST` request to `https://graph.codex.io/graphql` with your API key in the `Authorization` header.

To see a reference of all available queries, go to the [API Reference](https://docs.codex.io/api-reference/introduction.md).

## Examples

> [accordion] Try it
>
> [https://explorer.codex.io/embed.html?query=](https://explorer.codex.io/embed.html?query=)

> [accordion] SDK
>
> ```typescript theme={null}
> import { Codex } from "@codex-data/sdk"
>
> const sdk = new Codex("your-api-key")
>
> const { getTokenPrices } = await sdk.query(gql`
>   query {
>     getTokenPrices(inputs: [{ address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", networkId: 56 }]) {
>       priceUsd
>       timestamp
>       address
>     }
>   }
> `)
> ```

> [accordion] Custom
>
> ```typescript js theme={null}
> fetch("https://graph.codex.io/graphql", {
>   method: "POST",
>   headers: {
>     "Authorization": apiKey,
>   },
>   body: JSON.stringify({ query: 'query { getTokenPrices(inputs: [{ address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", networkId: 56 }]) { priceUsd timestamp address } }' }),
> })
> ```
>
> ```python python theme={null}
> import requests
> import json
>
> url = "https://graph.codex.io/graphql"
>
> headers = {
>   "content_type":"application/json",
>   "Authorization": "<MY_KEY>"
> }
>
> getNetworks = """query GetNetworksQuery { getNetworks { name id } }"""
>
> response = requests.post(url, headers=headers, json={"query": getNetworks})
>
> print(json.loads(response.text))
> ```
>
> ```php php theme={null}
> <?php
>
> $url = "https://graph.codex.io/graphql";
>
> $query = array(
>     'query' => '{
>         getNetworks {
>             name
>             id
>         }
>     }'
> );
>
> $headers = array(
>     'Content-Type: application/json',
>     'Authorization: ' . "<MY_KEY>"
> );
>
> $ch = curl_init($url);
> curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($query));
> curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
>
> $response = curl_exec($ch);
> curl_close($ch);
>
> echo $response;
> ```
>
> ```go go theme={null}
> package main
>
> import (
>   "bytes"
>   "fmt"
>   "net/http"
>   "io/ioutil"
>   "encoding/json"
> )
>
> func main() {
>   url := "https://graph.codex.io/graphql"
>   apiKey := "<MY_KEY>"
>
>   query := `query GetNetworksQuery { getNetworks { name id } }`
>   payload := map[string]string{"query": query}
>   payloadBytes, _ := json.Marshal(payload)
>
>   req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payloadBytes))
>   req.Header.Set("Content-Type", "application/json")
>   req.Header.Set("Authorization", apiKey)
>
>   client := &http.Client{}
>   res, _ := client.Do(req)
>   defer res.Body.Close()
>
>   body, _ := ioutil.ReadAll(res.Body)
>
>   var response map[string]interface{}
>   json.Unmarshal(body, &response)
>
>   fmt.Println(response)
> }
>
> ```
>
> ```ruby ruby theme={null}
> require 'net/http'
> require 'json'
>
> uri = URI('https://graph.codex.io/graphql')
> http = Net::HTTP.new(uri.host, uri.port)
> http.use_ssl = true
>
> headers = {
>   'Content-Type' => 'application/json',
>   'Authorization' => '<MY_KEY>'
> }
>
> query = {
>   query: '{
>     getNetworks {
>       name
>       id
>     }
>   }'
> }
>
> request = Net::HTTP::Post.new(uri.path, headers)
> request.body = query.to_json
>
> response = http.request(request)
> puts response.body
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.