Skip to content

Commit f5acd2f

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

File tree

3 files changed

+238
-2
lines changed

3 files changed

+238
-2
lines changed

‎docs/api/token-api.mdx

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: Token API
3+
image: /img/socialCards/linea-sdk.jpg
4+
---
5+
6+
The Token API provides comprehensive programmatic access to token data on the Linea network.
7+
This API is designed for developers, builders and analysts who need detailed information about ERC-20 tokens and their activities on Linea.
8+
9+
:::warning[Alpha Version Disclaimer]
10+
Linea's Token API is an alpha version and is subject to breaking changes.
11+
We recommend using it for testing and development purposes only.
12+
:::
13+
14+
### Key use cases
15+
16+
- Building automated trading bots
17+
- Creating token monitoring dashboards
18+
- Performing onchain data analysis
19+
- DeFi application integration
20+
- Wallet and transaction tracking
21+
22+
## Data sources
23+
24+
### Data collection
25+
26+
Data is collected from multiple sources:
27+
28+
1. **Onchain Data**
29+
- Smart contract state (name, symbol, decimals)
30+
31+
2. **External Sources**
32+
- [CoinGecko](https://www.coingecko.com/en/api)
33+
- [MetaMask Token API](https://docs.cx.metamask.io/docs/token-v2/)
34+
- [MetaMask Price API](https://docs.cx.metamask.io/docs/price/)
35+
- [Pond.fun](https://pond.fun/)
36+
- [Dune Analytics](https://dune.com/)
37+
38+
### Data updates
39+
40+
Linea Token API data updates at various intervals, depending on the data type.
41+
42+
- Token detection and metadata: every two hours
43+
- Historical prices: every hour
44+
- Current prices: every five minutes
45+
46+
## API endpoints
47+
48+
### Tokens
49+
50+
#### Get `/api/tokens`
51+
52+
Retrieve a 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 bonded 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+
152+
#### Get `/api/tokens/most-swapped`
153+
154+
Retrieve the most swapped tokens over the last 24 hours (from the [corresponding Dune query](https://dune.com/queries/4396527)).
155+
156+
<details>
157+
<summary>**Response**</summary>
158+
```json
159+
[
160+
{
161+
"name": "Foxy",
162+
"symbol": "FOXY",
163+
"decimals": 18,
164+
"logo": "https://i.ibb.co/MSKkFbf/logo.png",
165+
"contractAddress": "0x5fbdf89403270a1846f5ae7d113a989f850d1566",
166+
"currentPrice": "0.01080016000000",
167+
"priceUpdatedAt": "2025-01-09T09:50:05.106Z",
168+
"info": {
169+
"prices": [
170+
{
171+
"price": "0.01078276000000",
172+
"date": "2025-01-09T09:00:00.000Z"
173+
}
174+
],
175+
"sells": 219,
176+
"buys": 212,
177+
"graduatedAt": null
178+
}
179+
}
180+
]
181+
```
182+
</details>
183+
184+
## Usage examples
185+
186+
### Simple trading bot
187+
188+
```typescript
189+
async function monitorPriceChange(contractAddress: string, threshold: number) {
190+
const BASE_URL = 'https://not.live.yet';
191+
const initialPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
192+
193+
setInterval(async () => {
194+
const currentPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
195+
const priceChange = (currentPrice.price.usd - initialPrice.price.usd) / initialPrice.price.usd;
196+
197+
if (Math.abs(priceChange) > threshold) {
198+
// Execute trading strategy
199+
console.log(`Price changed by ${priceChange}% - Trading signal`);
200+
}
201+
}, 60000); // Check every minute
202+
}
203+
```
204+
205+
## Best practices
206+
207+
1. **Rate limiting**
208+
- This is an alpha version, with a low rate limit
209+
- Cache static data
210+
211+
2. **Error handling**
212+
- Always check HTTP status of responses
213+
- Implement retry with exponential backoff
214+
- Validate token addresses before requests
215+
216+
3. **Performance**
217+
- (Not available yet) Use pagination for large lists
218+
- Implement local caching when appropriate
219+
220+
## Security considerations
221+
222+
- Validate all input parameters
223+
- Sanitize response data
224+
225+
## Support and feedback
226+
227+
For technical support or feature requests, reach out to us on [Discord](https://discord.com/invite/linea).

‎mlc_config.json

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,15 @@
3232
},
3333
{
3434
"pattern": "https://portfolio.metamask.io/bridge"
35+
},
36+
{
37+
"pattern": "https://www.coingecko.com/en/api"
38+
},
39+
{
40+
"pattern": "https://dune.com/"
41+
},
42+
{
43+
"pattern": "https://dune.com/queries/4396527"
3544
}
3645
]
3746
}
38-

‎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)