Skip to content

Commit a2b405f

Browse files
benfacebenface
committed
Add endpoint-pricing and upgrade-to-v1 pages
1 parent aa74622 commit a2b405f

File tree

4 files changed

+308
-0
lines changed

4 files changed

+308
-0
lines changed

‎website/src/pages/en/token-api/_meta.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,7 @@ import titles from './_meta-titles.json'
33
export default {
44
'quick-start': '',
55
v1: titles.v1 ?? '',
6+
'endpoint-pricing': '',
67
faq: '',
8+
'upgrade-to-v1': '',
79
}

‎website/src/pages/en/token-api/endpoint-pricing.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Endpoint Pricing
3+
---
4+
5+
## Metadata Endpoints
6+
7+
| Endpoint | Price |
8+
| ----------------------- | ------------------- |
9+
| GET /v1/health | Free |
10+
| GET /v1/version | Free |
11+
| GET /v1/networks | Free |
12+
| GET /v1/evm/tokens | $15/million queries |
13+
| GET /v1/evm/balances | $15/million queries |
14+
| GET /v1/evm/pools | $15/million queries |
15+
| GET /v1/evm/dexes | $15/million queries |
16+
| GET /v1/evm/nft/holders | $15/million queries |
17+
| GET /v1/evm/nft/items | $15/million queries |
18+
| GET /v1/svm/tokens | $15/million queries |
19+
| GET /v1/svm/owner | $15/million queries |
20+
| GET /v1/svm/holders | $15/million queries |
21+
| GET /v1/svm/dexes | $15/million queries |
22+
23+
## Activity Endpoints
24+
25+
| Endpoint | Price |
26+
| --------------------------- | ------------------- |
27+
| GET /v1/evm/nft/transfers | $50/million queries |
28+
| GET /v1/evm/transfers | $50/million queries |
29+
| GET /v1/evm/nft/collections | $50/million queries |
30+
| GET /v1/evm/nft/ownerships | $50/million queries |
31+
| GET /v1/evm/nft/sales | $50/million queries |
32+
33+
## Balance Endpoints
34+
35+
| Endpoint | Price |
36+
| ------------------------------- | -------------------- |
37+
| GET /v1/evm/holders | $200/million queries |
38+
| GET /v1/evm/balances/historical | $200/million queries |
39+
| GET /v1/evm/swaps | $400/million queries |
40+
| GET /v1/svm/balances | $200/million queries |
41+
| GET /v1/svm/balances/native | $200/million queries |
42+
| GET /v1/svm/transfers | $200/million queries |
43+
| GET /v1/svm/swaps | $200/million queries |
44+
| GET /v1/svm/pools | $200/million queries |
45+
46+
## Historical Price Endpoints
47+
48+
| Endpoint | Price |
49+
| ---------------------- | -------------------- |
50+
| GET /v1/evm/pools/ohlc | $400/million queries |
51+
| GET /v1/svm/pools/ohlc | $400/million queries |

‎website/src/pages/en/token-api/faq.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Token API FAQ
3+
sidebarTitle: FAQ
34
---
45

56
Get fast answers to easily integrate and scale with The Graph's high-performance Token API.

‎website/src/pages/en/token-api/upgrade-to-v1.mdx‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
---
2+
title: Upgrade to V1
3+
---
4+
5+
This guide covers the migration from the legacy API structure to the new v1 API. The refactoring introduces versioned endpoints, standardized query parameters, improved batching support, and consistent naming conventions.
6+
7+
**Note**
8+
9+
- `EVM` = Ethereum Virtual Machine
10+
11+
Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...).
12+
13+
- `SVM` = Solana Virtual Machine
14+
15+
Used to describe endpoints supporting Solana (currently the only SVM chain supported).
16+
17+
## 🔑 Breaking Changes Summary
18+
19+
### 1. **API Versioning**
20+
21+
All endpoints now use the `/v1` prefix.
22+
23+
**Before:**
24+
25+
```
26+
GET /balances/evm
27+
GET /nft/items/contract/:contract/token_id/:token_id
28+
```
29+
30+
**After:**
31+
32+
```
33+
GET /v1/evm/balances
34+
GET /v1/evm/nft/items
35+
```
36+
37+
### 2. **Route Structure Reorganization**
38+
39+
#### 2.1 EVM Endpoints
40+
41+
Consolidated under `/v1/evm/*`
42+
43+
| Old Endpoint | New Endpoint |
44+
| ------------------------------------------------------ | ----------------------------- |
45+
| `/balances/evm` | `/v1/evm/balances` |
46+
| `/historical/balances/evm` | `/v1/evm/balances/historical` |
47+
| `/holders/evm/:contract` | `/v1/evm/holders` |
48+
| `/tokens/evm/:contract` | `/v1/evm/tokens` |
49+
| `/transfers/evm` | `/v1/evm/transfers` |
50+
| `/pools/evm` | `/v1/evm/pools` |
51+
| `/swaps/evm` | `/v1/evm/swaps` |
52+
| `/dexes/evm` | `/v1/evm/dexes` |
53+
| `/ohlc/prices/evm/:contract` | _(removed)_ |
54+
| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` |
55+
| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` |
56+
| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` |
57+
| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` |
58+
| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` |
59+
| `/nft/activities/evm` | `/v1/evm/nft/transfers` |
60+
| `/nft/sales/evm` | `/v1/evm/nft/sales` |
61+
62+
**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose.
63+
64+
**Important:** The EVM Token OHLCV Data endpoint `/ohlc/prices/evm/{contract}` has been removed. You can use `/v1/evm/pools` to find stablecoin pairs for your contract and `/v1/evm/pools/ohlc` for OHLCV data for that pair.
65+
66+
---
67+
68+
#### 2.2 New EVM native balances endpoint
69+
70+
Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint.
71+
72+
Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract.
73+
74+
---
75+
76+
#### 2.3 SVM Endpoints
77+
78+
Consolidated under `/v1/svm/*`
79+
80+
| Old Endpoint | New Endpoint |
81+
| ------------------------ | ------------------------- |
82+
| `/balances/svm` | `/v1/svm/balances` |
83+
| `/balances/native/svm` | `/v1/svm/balances/native` |
84+
| `/holders/svm/:contract` | `/v1/svm/holders` |
85+
| `/tokens/svm/:mint` | `/v1/svm/tokens` |
86+
| `/transfers/svm` | `/v1/svm/transfers` |
87+
| `/pools/svm` | `/v1/svm/pools` |
88+
| `/swaps/svm` | `/v1/svm/swaps` |
89+
| `/dexes/svm` | `/v1/svm/dexes` |
90+
| `/owner/svm/:account` | `/v1/svm/owner` |
91+
| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` |
92+
93+
## 📝 Parameter Changes
94+
95+
### 3. **Path Parameters → Query Parameters**
96+
97+
All path parameters have been moved to query parameters.
98+
99+
**Before:**
100+
101+
```bash
102+
GET /balances/evm/:address
103+
GET /holders/evm/:contract
104+
GET /nft/items/evm/contract/:contract/token_id/:token_id
105+
```
106+
107+
**After:**
108+
109+
```bash
110+
GET /v1/evm/balances?network=mainnet&address=0x...
111+
GET /v1/evm/holders?network=mainnet&contract=0x...
112+
GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712
113+
```
114+
115+
### 4. **Standardized Parameter Naming**
116+
117+
All query parameters have been standardized to use snake_case naming convention.
118+
119+
| Old Parameter | New Parameter | Notes |
120+
| --- | --- | --- |
121+
| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` |
122+
| `anyAddress` | `address` | Matches either `from` or `to` address |
123+
| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - |
124+
| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - |
125+
| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) |
126+
| `endTime` | `end_time` | Default: `9999999999` |
127+
| - | `start_block` | New parameter, default: `0` |
128+
| - | `end_block` | New parameter, default: `9999999999` |
129+
| - | `include_null_balances` | New parameter, default: `false` |
130+
| `tx_hash` | `transaction_id` | - |
131+
| `token` | `input_token`, `output_token` | More explicit for pool queries |
132+
| `pool` | `amm_pool` | - |
133+
| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first |
134+
135+
**Important:** The `network_id` parameter has been renamed to `network`.
136+
137+
**Important:** `matic` network has been renamed to `polygon`.
138+
139+
### 5. **Batched Parameters**
140+
141+
Many parameters now support batching - accepting single values or comma-separated strings.
142+
143+
**Supported Batched Parameters:**
144+
145+
- `address`, `from_address`, `to_address`
146+
- `contract`, `token_id`
147+
- `factory`, `pool`
148+
- `owner`, `token_account`, `mint`
149+
- `transaction_id`, `signature`
150+
151+
**Examples:**
152+
153+
```console
154+
# Single value
155+
?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
156+
157+
# Comma-separated, single parameter
158+
?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
159+
160+
# Repeated parameter values
161+
?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
162+
```
163+
164+
### 6. **New Parameters**
165+
166+
#### `include_null_balances`
167+
168+
Added to balance endpoints to optionally include zero/null balances.
169+
170+
```bash
171+
?include_null_balances=true
172+
```
173+
174+
**Default:** `false`
175+
176+
## 🔄 Response Changes
177+
178+
### 7. **Pagination Changes**
179+
180+
Pagination responses have been simplified. The API no longer computes total result counts due to performance and accuracy considerations when working with ClickHouse views and materialized tables.
181+
182+
**Before:**
183+
184+
```json
185+
{
186+
"pagination": {
187+
"previous_page": 1,
188+
"current_page": 2,
189+
"next_page": 3,
190+
"total_pages": 10
191+
},
192+
"total_results": 1234
193+
}
194+
```
195+
196+
**After:**
197+
198+
```json
199+
{
200+
"pagination": {
201+
"previous_page": 1,
202+
"current_page": 2
203+
}
204+
}
205+
```
206+
207+
**Removed fields:**
208+
209+
- `next_page`
210+
- `total_pages`
211+
- `total_results`
212+
213+
**Important:** To retrieve all results, continue incrementing the `page` parameter until the API returns an empty `data` array. This indicates you've reached the end of the results.
214+
215+
### 8. **Removed Parameters**
216+
217+
The following deprecated parameters have been removed:
218+
219+
- `orderBy` - Results are now ordered by timestamp/block by default
220+
- `orderDirection` - Always descending (newest first)
221+
222+
## 📚 Example Migrations
223+
224+
### Old vs New: Get Token Balances
225+
226+
**Before:**
227+
228+
```bash
229+
GET /balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
230+
```
231+
232+
**After:**
233+
234+
```bash
235+
GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
236+
```
237+
238+
### New Feature: Batched Queries
239+
240+
Query balances for multiple contracts in a single request:
241+
242+
```bash
243+
GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
244+
```
245+
246+
## ⚠️ Important Notes
247+
248+
1. **Backward Compatibility:** The old endpoints are deprecated and will be removed in the future. Migrate by **Oct 30, 2025**.
249+
250+
2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported.
251+
252+
3. **Pagination:** Continue paging through results by incrementing the `page` parameter until you receive an empty `data` array. The API no longer provides total counts due to performance optimizations with ClickHouse.
253+
254+
4. **Time Defaults:** If you previously relied on fetching all historical data without time filters, note that `start_time` now defaults to `2025-01-01`. Adjust accordingly if you need earlier data.

0 commit comments

Comments
 (0)