Skip to content

Commit 3b4d308

Browse files
alainnclsalainncls
committed
doc: Alpha Token API
1 parent 8b86387 commit 3b4d308

File tree

2 files changed

+228
-1
lines changed

2 files changed

+228
-1
lines changed

‎docs/api/token-api.mdx

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
---
2+
title: (Alpha) Token API
3+
image: /img/socialCards/linea-sdk.jpg
4+
---
5+
6+
## Overview
7+
8+
The Token API provides comprehensive programmatic access to token data on the Linea network.
9+
This API is designed for developers, builders and analysts who need detailed information about ERC-20 tokens and their activities on Linea.
10+
11+
:::warning[Alpha Version Disclaimer]
12+
Linea's Token API is an alpha version and is subject to breaking changes.
13+
We recommend using it for testing and development purposes only.
14+
:::
15+
16+
### Key use cases
17+
18+
- Building automated trading bots
19+
- Creating token monitoring dashboards
20+
- Performing on chain data analysis
21+
- DeFi application integration
22+
- Wallet and transaction tracking
23+
24+
## Data sources
25+
26+
### Data collection
27+
28+
Data is collected from multiple sources:
29+
30+
1. **On chain Data**
31+
- Smart contract state (name, symbol, decimals)
32+
33+
2. **External Sources**
34+
- [CoinGecko](https://www.coingecko.com/en/api)
35+
- [MetaMask Token](https://docs.cx.metamask.io/docs/token-v2/)
36+
- [MetaMask Price](https://docs.cx.metamask.io/docs/price/)
37+
- [Pond.fun](https://pond.fun/)
38+
- [Dune Analytics](https://dune.com/)
39+
40+
### Data updates
41+
42+
- Periodic synchronization (every 2 hours) for token detection and metadata
43+
- Periodic synchronization (every 1 hour) for historical prices
44+
- Periodic synchronization (every 5 minutes) for current prices
45+
46+
## API endpoints
47+
48+
### Tokens
49+
50+
#### GET `/api/tokens`
51+
52+
Retrieve the list of all available tokens on Linea.
53+
54+
<details>
55+
<summary>**Response**</summary>
56+
```json
57+
[
58+
{
59+
"name": "Wrapped Ether",
60+
"symbol": "WETH",
61+
"decimals": 18,
62+
"logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",
63+
"contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",
64+
"currentPrice": "3321.74000000000000",
65+
"priceUpdatedAt": "2025-01-09T09:36:02.194Z",
66+
"info": {
67+
"prices": [
68+
{
69+
"price": "3321.74000000000000",
70+
"date": "2025-01-09T09:00:00.000Z"
71+
}
72+
],
73+
"sells": 3279,
74+
"buys": 3722,
75+
"graduatedAt": null
76+
}
77+
}
78+
]
79+
```
80+
</details>
81+
82+
#### GET `/api/tokens/{contractAddress}`
83+
84+
Retrieve detailed information for a specific token.
85+
86+
**Parameters**
87+
88+
| Parameter | Type | Required | Description |
89+
|-------------------|--------|----------|-----------------|
90+
| contractAddress | string | Yes | Token address |
91+
92+
<details>
93+
<summary>**Response**</summary>
94+
```json
95+
{
96+
"name": "Wrapped Ether",
97+
"symbol": "WETH",
98+
"decimals": 18,
99+
"logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",
100+
"contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",
101+
"currentPrice": "3321.74000000000000",
102+
"priceUpdatedAt": "2025-01-09T09:36:02.194Z",
103+
"info": {
104+
"prices": [
105+
{
106+
"price": "3321.74000000000000",
107+
"date": "2025-01-09T09:00:00.000Z"
108+
}
109+
],
110+
"sells": 3279,
111+
"buys": 3722,
112+
"graduatedAt": null
113+
}
114+
}
115+
```
116+
</details>
117+
118+
### Prices
119+
120+
#### GET `/api/tokens/new-gems`
121+
122+
Retrieve recently bounded tokens from the [Pond.fun](https://pond.fun/) launchpad.
123+
124+
<details>
125+
<summary>**Response**</summary>
126+
```json
127+
[
128+
{
129+
"name": "CatWifCap",
130+
"symbol": "CWC",
131+
"decimals": 18,
132+
"logo": "https://d12kvghf2eznx1.cloudfront.net/tokens/images/d0a931cd-7982-47e4-86c7-74be11ab0b09",
133+
"contractAddress": "0x092b9e25a7d143c83d44c27194f5cee7c1150f22",
134+
"currentPrice": "0.00013412000000",
135+
"priceUpdatedAt": "2025-01-09T09:45:04.799Z",
136+
"info": {
137+
"prices": [
138+
{
139+
"price": "0.00013412000000",
140+
"date": "2025-01-09T09:00:00.000Z"
141+
}
142+
],
143+
"sells": 0,
144+
"buys": 0,
145+
"graduatedAt": "2024-12-01T18:19:42.095Z"
146+
}
147+
}
148+
]
149+
```
150+
</details>
151+
#### GET `/api/tokens/most-swapped`
152+
153+
Retrieves most swapped tokens over the last 24 hours (from the [corresponding Dune query](https://dune.com/queries/4396527)).
154+
155+
<details>
156+
<summary>**Response**</summary>
157+
```json
158+
[
159+
{
160+
"name": "Foxy",
161+
"symbol": "FOXY",
162+
"decimals": 18,
163+
"logo": "https://i.ibb.co/MSKkFbf/logo.png",
164+
"contractAddress": "0x5fbdf89403270a1846f5ae7d113a989f850d1566",
165+
"currentPrice": "0.01080016000000",
166+
"priceUpdatedAt": "2025-01-09T09:50:05.106Z",
167+
"info": {
168+
"prices": [
169+
{
170+
"price": "0.01078276000000",
171+
"date": "2025-01-09T09:00:00.000Z"
172+
}
173+
],
174+
"sells": 219,
175+
"buys": 212,
176+
"graduatedAt": null
177+
}
178+
}
179+
]
180+
```
181+
</details>
182+
183+
## Usage examples
184+
185+
### Simple trading bot creation
186+
187+
```typescript
188+
async function monitorPriceChange(contractAddress: string, threshold: number) {
189+
const BASE_URL = 'https://not.live.yet';
190+
const initialPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
191+
192+
setInterval(async () => {
193+
const currentPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
194+
const priceChange = (currentPrice.price.usd - initialPrice.price.usd) / initialPrice.price.usd;
195+
196+
if (Math.abs(priceChange) > threshold) {
197+
// Execute trading strategy
198+
console.log(`Price changed by ${priceChange}% - Trading signal`);
199+
}
200+
}, 60000); // Check every minute
201+
}
202+
```
203+
204+
## Best practices
205+
206+
1. **Rate Limiting**
207+
- This is an alpha version, with a low rate limit
208+
- Cache static data
209+
210+
2. **Error Handling**
211+
- Always check HTTP status of responses
212+
- Implement retry with exponential backoff
213+
- Validate token addresses before requests
214+
215+
3. **Performance**
216+
- (Not available yet) Use pagination for large lists
217+
- Implement local caching when appropriate
218+
219+
## Security considerations
220+
221+
- Validate all input parameters
222+
- Sanitize response data
223+
224+
## Support and feedback
225+
226+
For technical support or feature requests, reach out to us on [Discord](https://discord.com/invite/linea).

‎sidebars.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
1+
/** @type {import("@docusaurus/plugin-content-docs").SidebarsConfig} */
22
const sidebars = {
33
getStartedSidebar: [
44
{
@@ -573,6 +573,7 @@ const sidebars = {
573573
},
574574
],
575575
},
576+
"api/token-api",
576577
],
577578
technologySidebar: [
578579
"technology/architecture",

0 commit comments

Comments
 (0)