diff --git a/website/route-lockfile.txt b/website/route-lockfile.txt index 098bfe022482..c0a8265106b5 100644 --- a/website/route-lockfile.txt +++ b/website/route-lockfile.txt @@ -287,7 +287,6 @@ /ar/token-api/tvm-tokens/tokens/ /ar/token-api/tvm-tokens/transfers-native/ /ar/token-api/tvm-tokens/transfers/ -/ar/token-api/upgrade-to-v1/ /cs/ /cs/404/ /cs/about/ @@ -576,7 +575,6 @@ /cs/token-api/tvm-tokens/tokens/ /cs/token-api/tvm-tokens/transfers-native/ /cs/token-api/tvm-tokens/transfers/ -/cs/token-api/upgrade-to-v1/ /de/ /de/404/ /de/about/ @@ -865,7 +863,6 @@ /de/token-api/tvm-tokens/tokens/ /de/token-api/tvm-tokens/transfers-native/ /de/token-api/tvm-tokens/transfers/ -/de/token-api/upgrade-to-v1/ /en/ /en/404/ /en/about/ @@ -1135,7 +1132,6 @@ /en/token-api/evm-tokens/transfers/ /en/token-api/faq/ /en/token-api/guides/gpt/ -/en/token-api/guides/upgrade-to-v1/ /en/token-api/monitoring/health/ /en/token-api/monitoring/networks/ /en/token-api/monitoring/version/ @@ -1444,7 +1440,6 @@ /es/token-api/tvm-tokens/tokens/ /es/token-api/tvm-tokens/transfers-native/ /es/token-api/tvm-tokens/transfers/ -/es/token-api/upgrade-to-v1/ /fr/ /fr/404/ /fr/about/ @@ -1733,7 +1728,6 @@ /fr/token-api/tvm-tokens/tokens/ /fr/token-api/tvm-tokens/transfers-native/ /fr/token-api/tvm-tokens/transfers/ -/fr/token-api/upgrade-to-v1/ /hi/ /hi/404/ /hi/about/ @@ -2022,7 +2016,6 @@ /hi/token-api/tvm-tokens/tokens/ /hi/token-api/tvm-tokens/transfers-native/ /hi/token-api/tvm-tokens/transfers/ -/hi/token-api/upgrade-to-v1/ /it/ /it/404/ /it/about/ @@ -2311,7 +2304,6 @@ /it/token-api/tvm-tokens/tokens/ /it/token-api/tvm-tokens/transfers-native/ /it/token-api/tvm-tokens/transfers/ -/it/token-api/upgrade-to-v1/ /ja/ /ja/404/ /ja/about/ @@ -2600,7 +2592,6 @@ /ja/token-api/tvm-tokens/tokens/ /ja/token-api/tvm-tokens/transfers-native/ /ja/token-api/tvm-tokens/transfers/ -/ja/token-api/upgrade-to-v1/ /ko/about/ /ko/ai-suite/ai-introduction/ /ko/ai-suite/subgraph-mcp/claude/ @@ -2737,7 +2728,6 @@ /ko/token-api/tvm-tokens/tokens/ /ko/token-api/tvm-tokens/transfers-native/ /ko/token-api/tvm-tokens/transfers/ -/ko/token-api/upgrade-to-v1/ /mr/ /mr/404/ /mr/about/ @@ -3026,7 +3016,6 @@ /mr/token-api/tvm-tokens/tokens/ /mr/token-api/tvm-tokens/transfers-native/ /mr/token-api/tvm-tokens/transfers/ -/mr/token-api/upgrade-to-v1/ /nl/about/ /nl/ai-suite/ai-introduction/ /nl/ai-suite/subgraph-mcp/claude/ @@ -3163,7 +3152,6 @@ /nl/token-api/tvm-tokens/tokens/ /nl/token-api/tvm-tokens/transfers-native/ /nl/token-api/tvm-tokens/transfers/ -/nl/token-api/upgrade-to-v1/ /pl/about/ /pl/ai-suite/ai-introduction/ /pl/ai-suite/subgraph-mcp/claude/ @@ -3300,7 +3288,6 @@ /pl/token-api/tvm-tokens/tokens/ /pl/token-api/tvm-tokens/transfers-native/ /pl/token-api/tvm-tokens/transfers/ -/pl/token-api/upgrade-to-v1/ /pt/ /pt/404/ /pt/about/ @@ -3589,7 +3576,6 @@ /pt/token-api/tvm-tokens/tokens/ /pt/token-api/tvm-tokens/transfers-native/ /pt/token-api/tvm-tokens/transfers/ -/pt/token-api/upgrade-to-v1/ /ro/about/ /ro/ai-suite/ai-introduction/ /ro/ai-suite/subgraph-mcp/claude/ @@ -3726,7 +3712,6 @@ /ro/token-api/tvm-tokens/tokens/ /ro/token-api/tvm-tokens/transfers-native/ /ro/token-api/tvm-tokens/transfers/ -/ro/token-api/upgrade-to-v1/ /ru/ /ru/404/ /ru/about/ @@ -4015,7 +4000,6 @@ /ru/token-api/tvm-tokens/tokens/ /ru/token-api/tvm-tokens/transfers-native/ /ru/token-api/tvm-tokens/transfers/ -/ru/token-api/upgrade-to-v1/ /sv/ /sv/404/ /sv/about/ @@ -4304,7 +4288,6 @@ /sv/token-api/tvm-tokens/tokens/ /sv/token-api/tvm-tokens/transfers-native/ /sv/token-api/tvm-tokens/transfers/ -/sv/token-api/upgrade-to-v1/ /tr/ /tr/404/ /tr/about/ @@ -4446,7 +4429,6 @@ /tr/token-api/tvm-tokens/tokens/ /tr/token-api/tvm-tokens/transfers-native/ /tr/token-api/tvm-tokens/transfers/ -/tr/token-api/upgrade-to-v1/ /uk/about/ /uk/ai-suite/ai-introduction/ /uk/ai-suite/subgraph-mcp/claude/ @@ -4583,7 +4565,6 @@ /uk/token-api/tvm-tokens/tokens/ /uk/token-api/tvm-tokens/transfers-native/ /uk/token-api/tvm-tokens/transfers/ -/uk/token-api/upgrade-to-v1/ /ur/ /ur/404/ /ur/about/ @@ -4722,7 +4703,6 @@ /ur/token-api/tvm-tokens/tokens/ /ur/token-api/tvm-tokens/transfers-native/ /ur/token-api/tvm-tokens/transfers/ -/ur/token-api/upgrade-to-v1/ /vi/about/ /vi/ai-suite/ai-introduction/ /vi/ai-suite/subgraph-mcp/claude/ @@ -4859,7 +4839,6 @@ /vi/token-api/tvm-tokens/tokens/ /vi/token-api/tvm-tokens/transfers-native/ /vi/token-api/tvm-tokens/transfers/ -/vi/token-api/upgrade-to-v1/ /zh/ /zh/404/ /zh/about/ @@ -4998,4 +4977,3 @@ /zh/token-api/tvm-tokens/tokens/ /zh/token-api/tvm-tokens/transfers-native/ /zh/token-api/tvm-tokens/transfers/ -/zh/token-api/upgrade-to-v1/ diff --git a/website/src/pages/ar/token-api/guides/_meta-titles.json b/website/src/pages/ar/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/ar/token-api/guides/_meta-titles.json +++ b/website/src/pages/ar/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/ar/token-api/guides/_meta.js b/website/src/pages/ar/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/ar/token-api/guides/_meta.js +++ b/website/src/pages/ar/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/ar/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/ar/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/ar/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/cs/token-api/guides/_meta-titles.json b/website/src/pages/cs/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/cs/token-api/guides/_meta-titles.json +++ b/website/src/pages/cs/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/cs/token-api/guides/_meta.js b/website/src/pages/cs/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/cs/token-api/guides/_meta.js +++ b/website/src/pages/cs/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/cs/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/cs/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/cs/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/de/token-api/guides/_meta-titles.json b/website/src/pages/de/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/de/token-api/guides/_meta-titles.json +++ b/website/src/pages/de/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/de/token-api/guides/_meta.js b/website/src/pages/de/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/de/token-api/guides/_meta.js +++ b/website/src/pages/de/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/de/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/de/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/de/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/en/token-api/guides/_meta-titles.json b/website/src/pages/en/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/en/token-api/guides/_meta-titles.json +++ b/website/src/pages/en/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/en/token-api/guides/_meta.js b/website/src/pages/en/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/en/token-api/guides/_meta.js +++ b/website/src/pages/en/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/en/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/en/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/en/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/es/token-api/guides/_meta-titles.json b/website/src/pages/es/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/es/token-api/guides/_meta-titles.json +++ b/website/src/pages/es/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/es/token-api/guides/_meta.js b/website/src/pages/es/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/es/token-api/guides/_meta.js +++ b/website/src/pages/es/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/es/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/es/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/es/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/fr/token-api/guides/_meta-titles.json b/website/src/pages/fr/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/fr/token-api/guides/_meta-titles.json +++ b/website/src/pages/fr/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/fr/token-api/guides/_meta.js b/website/src/pages/fr/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/fr/token-api/guides/_meta.js +++ b/website/src/pages/fr/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/fr/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/fr/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/fr/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/hi/token-api/guides/_meta-titles.json b/website/src/pages/hi/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/hi/token-api/guides/_meta-titles.json +++ b/website/src/pages/hi/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/hi/token-api/guides/_meta.js b/website/src/pages/hi/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/hi/token-api/guides/_meta.js +++ b/website/src/pages/hi/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/hi/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/hi/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/hi/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/it/token-api/guides/_meta-titles.json b/website/src/pages/it/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/it/token-api/guides/_meta-titles.json +++ b/website/src/pages/it/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/it/token-api/guides/_meta.js b/website/src/pages/it/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/it/token-api/guides/_meta.js +++ b/website/src/pages/it/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/it/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/it/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/it/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/ja/token-api/guides/_meta-titles.json b/website/src/pages/ja/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/ja/token-api/guides/_meta-titles.json +++ b/website/src/pages/ja/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/ja/token-api/guides/_meta.js b/website/src/pages/ja/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/ja/token-api/guides/_meta.js +++ b/website/src/pages/ja/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/ja/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/ja/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/ja/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/ko/token-api/guides/_meta-titles.json b/website/src/pages/ko/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/ko/token-api/guides/_meta-titles.json +++ b/website/src/pages/ko/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/ko/token-api/guides/_meta.js b/website/src/pages/ko/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/ko/token-api/guides/_meta.js +++ b/website/src/pages/ko/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/ko/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/ko/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/ko/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/mr/token-api/guides/_meta-titles.json b/website/src/pages/mr/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/mr/token-api/guides/_meta-titles.json +++ b/website/src/pages/mr/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/mr/token-api/guides/_meta.js b/website/src/pages/mr/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/mr/token-api/guides/_meta.js +++ b/website/src/pages/mr/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/mr/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/mr/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/mr/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/nl/token-api/guides/_meta-titles.json b/website/src/pages/nl/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/nl/token-api/guides/_meta-titles.json +++ b/website/src/pages/nl/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/nl/token-api/guides/_meta.js b/website/src/pages/nl/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/nl/token-api/guides/_meta.js +++ b/website/src/pages/nl/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/nl/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/nl/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/nl/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/pl/token-api/guides/_meta-titles.json b/website/src/pages/pl/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/pl/token-api/guides/_meta-titles.json +++ b/website/src/pages/pl/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/pl/token-api/guides/_meta.js b/website/src/pages/pl/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/pl/token-api/guides/_meta.js +++ b/website/src/pages/pl/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/pl/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/pl/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/pl/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/pt/token-api/guides/_meta-titles.json b/website/src/pages/pt/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/pt/token-api/guides/_meta-titles.json +++ b/website/src/pages/pt/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/pt/token-api/guides/_meta.js b/website/src/pages/pt/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/pt/token-api/guides/_meta.js +++ b/website/src/pages/pt/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/pt/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/pt/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/pt/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/ro/token-api/guides/_meta-titles.json b/website/src/pages/ro/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/ro/token-api/guides/_meta-titles.json +++ b/website/src/pages/ro/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/ro/token-api/guides/_meta.js b/website/src/pages/ro/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/ro/token-api/guides/_meta.js +++ b/website/src/pages/ro/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/ro/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/ro/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/ro/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/ru/token-api/guides/_meta-titles.json b/website/src/pages/ru/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/ru/token-api/guides/_meta-titles.json +++ b/website/src/pages/ru/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/ru/token-api/guides/_meta.js b/website/src/pages/ru/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/ru/token-api/guides/_meta.js +++ b/website/src/pages/ru/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/ru/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/ru/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/ru/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/sv/token-api/guides/_meta-titles.json b/website/src/pages/sv/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/sv/token-api/guides/_meta-titles.json +++ b/website/src/pages/sv/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/sv/token-api/guides/_meta.js b/website/src/pages/sv/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/sv/token-api/guides/_meta.js +++ b/website/src/pages/sv/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/sv/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/sv/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/sv/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/tr/token-api/guides/_meta-titles.json b/website/src/pages/tr/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/tr/token-api/guides/_meta-titles.json +++ b/website/src/pages/tr/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/tr/token-api/guides/_meta.js b/website/src/pages/tr/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/tr/token-api/guides/_meta.js +++ b/website/src/pages/tr/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/tr/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/tr/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/tr/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/uk/token-api/guides/_meta-titles.json b/website/src/pages/uk/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/uk/token-api/guides/_meta-titles.json +++ b/website/src/pages/uk/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/uk/token-api/guides/_meta.js b/website/src/pages/uk/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/uk/token-api/guides/_meta.js +++ b/website/src/pages/uk/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/uk/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/uk/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/uk/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/ur/token-api/guides/_meta-titles.json b/website/src/pages/ur/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/ur/token-api/guides/_meta-titles.json +++ b/website/src/pages/ur/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/ur/token-api/guides/_meta.js b/website/src/pages/ur/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/ur/token-api/guides/_meta.js +++ b/website/src/pages/ur/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/ur/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/ur/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/ur/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/vi/token-api/guides/_meta-titles.json b/website/src/pages/vi/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/vi/token-api/guides/_meta-titles.json +++ b/website/src/pages/vi/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/vi/token-api/guides/_meta.js b/website/src/pages/vi/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/vi/token-api/guides/_meta.js +++ b/website/src/pages/vi/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/vi/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/vi/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/vi/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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. diff --git a/website/src/pages/zh/token-api/guides/_meta-titles.json b/website/src/pages/zh/token-api/guides/_meta-titles.json index cd93dcc0fc0b..31dc2ecb665f 100644 --- a/website/src/pages/zh/token-api/guides/_meta-titles.json +++ b/website/src/pages/zh/token-api/guides/_meta-titles.json @@ -1,4 +1,3 @@ { - "gpt": "Create Custom GPTS", - "upgrade-to-v1": "" + "gpt": "Create Custom GPTS" } diff --git a/website/src/pages/zh/token-api/guides/_meta.js b/website/src/pages/zh/token-api/guides/_meta.js index e5aaaadd78f2..a3bef99e3420 100644 --- a/website/src/pages/zh/token-api/guides/_meta.js +++ b/website/src/pages/zh/token-api/guides/_meta.js @@ -1,4 +1,3 @@ export default { gpt: '', - 'upgrade-to-v1': '', } diff --git a/website/src/pages/zh/token-api/guides/upgrade-to-v1.mdx b/website/src/pages/zh/token-api/guides/upgrade-to-v1.mdx deleted file mode 100644 index e2a7ccf973fa..000000000000 --- a/website/src/pages/zh/token-api/guides/upgrade-to-v1.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Upgrade to v1 ---- - -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. - -**Note** - -- `EVM` = Ethereum Virtual Machine - -Used to describe endpoints supporting EVM-based chains (e.g. `base`, `bsc`, `mainnet`, ...). - -- `SVM` = Solana Virtual Machine - -Used to describe endpoints supporting Solana (currently the only SVM chain supported). - -## 🔑 Breaking Changes Summary - -### 1. API Versioning - -All endpoints now use the `/v1` prefix. - -**Before:** - -``` -GET /balances/evm -GET /nft/items/contract/:contract/token_id/:token_id -``` - -**After:** - -``` -GET /v1/evm/balances -GET /v1/evm/nft/items -``` - -### 2. Route Structure Reorganization - -#### 2.1 EVM Endpoints - -Consolidated under `/v1/evm/*` - -| Old Endpoint | New Endpoint | -| ------------------------------------------------------ | ----------------------------- | -| `/balances/evm` | `/v1/evm/balances` | -| `/historical/balances/evm` | `/v1/evm/balances/historical` | -| `/holders/evm/:contract` | `/v1/evm/holders` | -| `/tokens/evm/:contract` | `/v1/evm/tokens` | -| `/transfers/evm` | `/v1/evm/transfers` | -| `/pools/evm` | `/v1/evm/pools` | -| `/swaps/evm` | `/v1/evm/swaps` | -| `/dexes/evm` | `/v1/evm/dexes` | -| `/ohlc/prices/evm/:contract` | _(removed)_ | -| `/ohlc/pools/evm/:pool` | `/v1/evm/pools/ohlc` | -| `/nft/ownerships/evm/:address` | `/v1/evm/nft/ownerships` | -| `/nft/collections/evm/:contract` | `/v1/evm/nft/collections` | -| `/nft/items/evm/contract/:contract/token_id/:token_id` | `/v1/evm/nft/items` | -| `/nft/holders/evm/:contract` | `/v1/evm/nft/holders` | -| `/nft/activities/evm` | `/v1/evm/nft/transfers` | -| `/nft/sales/evm` | `/v1/evm/nft/sales` | - -**Important:** The NFT endpoint `/nft/activities` has been renamed to `/v1/evm/nft/transfers` to better reflect its purpose. - -**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. - ---- - -#### 2.2 New EVM native balances endpoint - -Native balances for EVM chains can be found under `/v1/evm/balances/native`. They will not show up in the `/v1/evm/balances` endpoint. - -Other endpoints can still use native token under the `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` contract. - ---- - -#### 2.3 SVM Endpoints - -Consolidated under `/v1/svm/*` - -| Old Endpoint | New Endpoint | -| ------------------------ | ------------------------- | -| `/balances/svm` | `/v1/svm/balances` | -| `/balances/native/svm` | `/v1/svm/balances/native` | -| `/holders/svm/:contract` | `/v1/svm/holders` | -| `/tokens/svm/:mint` | `/v1/svm/tokens` | -| `/transfers/svm` | `/v1/svm/transfers` | -| `/pools/svm` | `/v1/svm/pools` | -| `/swaps/svm` | `/v1/svm/swaps` | -| `/dexes/svm` | `/v1/svm/dexes` | -| `/owner/svm/:account` | `/v1/svm/owner` | -| `/ohlc/pools/svm/:pool` | `/v1/svm/pools/ohlc` | - -## 📝 Parameter Changes - -### 3. Path Parameters → Query Parameters - -All path parameters have been moved to query parameters. - -**Before:** - -```bash -GET /balances/evm/:address -GET /holders/evm/:contract -GET /nft/items/evm/contract/:contract/token_id/:token_id -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0x... -GET /v1/evm/holders?network=mainnet&contract=0x... -GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712 -``` - -### 4. Standardized Parameter Naming - -All query parameters have been standardized to use snake_case naming convention. - -| Old Parameter | New Parameter | Notes | -| --- | --- | --- | -| `network_id` | `network` | Renamed, `matic` has also been renamed to `polygon` | -| `anyAddress` | `address` | Matches either `from` or `to` address | -| `from`, `fromAddress`, `offererAddress` | `from_address`, `offerer` | - | -| `to`, `toAddress`, `recipientAddress` | `to_address`, `recipient` | - | -| `startTime` | `start_time` | Default: `1735689600` (`2025-01-01`) | -| `endTime` | `end_time` | Default: `9999999999` | -| - | `start_block` | New parameter, default: `0` | -| - | `end_block` | New parameter, default: `9999999999` | -| - | `include_null_balances` | New parameter, default: `false` | -| `tx_hash` | `transaction_id` | - | -| `token` | `input_token`, `output_token` | More explicit for pool queries | -| `pool` | `amm_pool` | - | -| `orderBy`, `orderDirection` | _(removed)_ | Always sorted by most recent timestamp first | - -**Important:** The `network_id` parameter has been renamed to `network`. - -**Important:** `matic` network has been renamed to `polygon`. - -### 5. Batched Parameters - -Many parameters now support batching - accepting single values or comma-separated strings. - -**Supported Batched Parameters:** - -- `address`, `from_address`, `to_address` -- `contract`, `token_id` -- `factory`, `pool` -- `owner`, `token_account`, `mint` -- `transaction_id`, `signature` - -**Examples:** - -```console -## Single value -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 - -## Comma-separated, single parameter -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 - -## Repeated parameter values -?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -### 6. New Parameters - -#### `include_null_balances` - -Added to balance endpoints to optionally include zero/null balances. - -```bash -?include_null_balances=true -``` - -**Default:** `false` - -## 🔄 Response Changes - -### 7. Pagination Changes - -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. - -**Before:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2, - "next_page": 3, - "total_pages": 10 - }, - "total_results": 1234 -} -``` - -**After:** - -```json -{ - "pagination": { - "previous_page": 1, - "current_page": 2 - } -} -``` - -**Removed fields:** - -- `next_page` -- `total_pages` -- `total_results` - -**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. - -### 8. Removed Parameters - -The following deprecated parameters have been removed: - -- `orderBy` - Results are now ordered by timestamp/block by default -- `orderDirection` - Always descending (newest first) - -### 9. Cached Queries - -Queries are now cached on the ClickHouse side for better performance. - -You can specifically request to not use the cache by setting the `Cache-Control` header to `no-cache`. - -#### Example - -**Cache** - -```console -$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics -{ - "bytes_read": 221, - "rows_read": 1, - "elapsed": 0.002212065 -} -``` - -**No cache** - -```console -$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics -{ - "bytes_read": 14621174348, - "rows_read": 223244390, - "elapsed": 0.971064066 -} -``` - -## 📚 Example Migrations - -### Example 1: Get Token Balances - -**Before:** - -```bash -GET /token/balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -**After:** - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 -``` - -### Example 2: Get NFT Items - -**Before:** - -```bash -GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet -``` - -**After:** - -```bash -GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712 -``` - -### Example 3: Get Token Transfers with Time Filter - -**Before:** - -```bash -GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600 -``` - -**After:** - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600 -``` - -### Example 4: Get NFT Transfer Activities - -**Before:** - -```bash -GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -**After:** - -```bash -GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -``` - -### Example 5: Get Pool OHLC Data - -**Before:** - -```bash -GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600 -``` - -**After:** - -```bash -GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600 -``` - -### Example 6: Batched Query (New Feature) - -Query balances for multiple contracts in a single request: - -```bash -GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 -``` - -Query transfers from multiple addresses: - -```bash -GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600 -``` - -## ⚠️ Important Notes - -1. **Migration Notes:** The old endpoints were deprecated and removed on **October 30, 2025**. Please ensure all integrations have been migrated to the new Token API v1 endpoints. - -2. **Default Sorting:** All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported. - -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. - -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.