Skip to content

Commit

Permalink
doc: Alpha Token API
Browse files Browse the repository at this point in the history
  • Loading branch information
alainncls committed Jan 9, 2025
1 parent 8b86387 commit 06024c2
Show file tree
Hide file tree
Showing 3 changed files with 241 additions and 2 deletions.
230 changes: 230 additions & 0 deletions docs/api/token-api.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
---
title: Token API
image: /img/socialCards/linea-sdk.jpg
---

The Token API provides comprehensive programmatic access to token data on the Linea network.
This API is designed for developers, builders and analysts who need detailed information about ERC-20 tokens and their activities on Linea.

:::warning[Alpha Version Disclaimer]
Linea's Token API is an alpha version and is subject to breaking changes.
We recommend using it for testing and development purposes only.
We are looking for your feedback on this new service,
please reach out to us on [Discord](https://discord.com/invite/linea) in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024) channel.
:::

### Key use cases

- Building automated trading bots
- Creating token monitoring dashboards
- Performing onchain data analysis
- DeFi application integration
- Wallet and transaction tracking

## Data sources

### Data collection

Data is collected from multiple sources:

1. **Onchain Data**
- Smart contract state (name, symbol, decimals)

2. **External Sources**
- [CoinGecko](https://www.coingecko.com/en/api)
- [MetaMask Token API](https://docs.cx.metamask.io/docs/token-v2/)
- [MetaMask Price API](https://docs.cx.metamask.io/docs/price/)
- [Pond.fun](https://pond.fun/)
- [Dune Analytics](https://dune.com/)

### Data updates

Linea Token API data updates at various intervals, depending on the data type.

- Token detection and metadata: every two hours
- Historical prices: every hour
- Current prices: every five minutes

## API endpoints

### Tokens

#### Get `/api/tokens`

Retrieve a list of all available tokens on Linea.

<details>
<summary>**Response**</summary>
```json
[
{
"name": "Wrapped Ether",
"symbol": "WETH",
"decimals": 18,
"logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",

Check failure on line 64 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [proselint.Typography] Consider using the '×' symbol instead of '64x64'. Raw Output: {"message": "[proselint.Typography] Consider using the '×' symbol instead of '64x64'.", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 64, "column": 62}}}, "severity": "ERROR"}
"contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",

Check failure on line 65 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'contractAddress'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'contractAddress'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 65, "column": 8}}}, "severity": "ERROR"}
"currentPrice": "3321.74000000000000",

Check failure on line 66 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'currentPrice'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'currentPrice'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 66, "column": 8}}}, "severity": "ERROR"}
"priceUpdatedAt": "2025-01-09T09:36:02.194Z",
"info": {
"prices": [
{
"price": "3321.74000000000000",
"date": "2025-01-09T09:00:00.000Z"
}
],
"sells": 3279,
"buys": 3722,
"graduatedAt": null

Check failure on line 77 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'graduatedAt'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'graduatedAt'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 77, "column": 10}}}, "severity": "ERROR"}
}
}
]
```
</details>

#### Get `/api/tokens/{contractAddress}`

Retrieve detailed information for a specific token.

**Parameters**

| Parameter | Type | Required | Description |
|-------------------|--------|----------|-----------------|
| contractAddress | string | Yes | Token address |

Check failure on line 92 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'contractAddress'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'contractAddress'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 92, "column": 3}}}, "severity": "ERROR"}

<details>
<summary>**Response**</summary>
```json
{
"name": "Wrapped Ether",
"symbol": "WETH",
"decimals": 18,
"logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",

Check failure on line 101 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [proselint.Typography] Consider using the '×' symbol instead of '64x64'. Raw Output: {"message": "[proselint.Typography] Consider using the '×' symbol instead of '64x64'.", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 101, "column": 62}}}, "severity": "ERROR"}
"contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",

Check failure on line 102 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'contractAddress'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'contractAddress'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 102, "column": 8}}}, "severity": "ERROR"}
"currentPrice": "3321.74000000000000",

Check failure on line 103 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'currentPrice'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'currentPrice'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 103, "column": 8}}}, "severity": "ERROR"}
"priceUpdatedAt": "2025-01-09T09:36:02.194Z",
"info": {
"prices": [
{
"price": "3321.74000000000000",
"date": "2025-01-09T09:00:00.000Z"
}
],
"sells": 3279,
"buys": 3722,
"graduatedAt": null

Check failure on line 114 in docs/api/token-api.mdx

View workflow job for this annotation

GitHub Actions / Spelling

[vale] reported by reviewdog 🐶 [Vale.Spelling] Did you really mean 'graduatedAt'? Raw Output: {"message": "[Vale.Spelling] Did you really mean 'graduatedAt'?", "location": {"path": "docs/api/token-api.mdx", "range": {"start": {"line": 114, "column": 12}}}, "severity": "ERROR"}
}
}
```
</details>

### Prices

#### Get `/api/tokens/new-gems`

Retrieve recently bonded tokens from the [Pond.fun](https://pond.fun/) launchpad.

<details>
<summary>**Response**</summary>
```json
[
{
"name": "CatWifCap",
"symbol": "CWC",
"decimals": 18,
"logo": "https://d12kvghf2eznx1.cloudfront.net/tokens/images/d0a931cd-7982-47e4-86c7-74be11ab0b09",
"contractAddress": "0x092b9e25a7d143c83d44c27194f5cee7c1150f22",
"currentPrice": "0.00013412000000",
"priceUpdatedAt": "2025-01-09T09:45:04.799Z",
"info": {
"prices": [
{
"price": "0.00013412000000",
"date": "2025-01-09T09:00:00.000Z"
}
],
"sells": 0,
"buys": 0,
"graduatedAt": "2024-12-01T18:19:42.095Z"
}
}
]
```
</details>

#### Get `/api/tokens/most-swapped`

Retrieve the most swapped tokens over the last 24 hours (from the [corresponding Dune query](https://dune.com/queries/4396527)).

<details>
<summary>**Response**</summary>
```json
[
{
"name": "Foxy",
"symbol": "FOXY",
"decimals": 18,
"logo": "https://i.ibb.co/MSKkFbf/logo.png",
"contractAddress": "0x5fbdf89403270a1846f5ae7d113a989f850d1566",
"currentPrice": "0.01080016000000",
"priceUpdatedAt": "2025-01-09T09:50:05.106Z",
"info": {
"prices": [
{
"price": "0.01078276000000",
"date": "2025-01-09T09:00:00.000Z"
}
],
"sells": 219,
"buys": 212,
"graduatedAt": null
}
}
]
```
</details>

## Usage examples

### Simple trading bot

```typescript
async function monitorPriceChange(contractAddress: string, threshold: number) {
const BASE_URL = 'https://not.live.yet';
const initialPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());

setInterval(async () => {
const currentPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
const priceChange = (currentPrice.price.usd - initialPrice.price.usd) / initialPrice.price.usd;

if (Math.abs(priceChange) > threshold) {
// Execute trading strategy
console.log(`Price changed by ${priceChange}% - Trading signal`);
}
}, 60000); // Check every minute
}
```

## Best practices

1. **Rate limiting**
- This is an alpha version, with a low rate limit
- Cache static data

2. **Error handling**
- Always check HTTP status of responses
- Implement retry with exponential backoff
- Validate token addresses before requests

3. **Performance**
- (Not available yet) Use pagination for large lists
- Implement local caching when appropriate

## Security considerations

- Validate all input parameters
- Sanitize response data

## Support and feedback

For technical support or feature requests,
reach out to us on [Discord](https://discord.com/invite/linea) in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024) channel.
10 changes: 9 additions & 1 deletion mlc_config.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,15 @@
},
{
"pattern": "https://portfolio.metamask.io/bridge"
},
{
"pattern": "https://www.coingecko.com/en/api"
},
{
"pattern": "https://dune.com/"
},
{
"pattern": "https://dune.com/queries/4396527"
}
]
}

3 changes: 2 additions & 1 deletion sidebars.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
/** @type {import("@docusaurus/plugin-content-docs").SidebarsConfig} */
const sidebars = {
getStartedSidebar: [
{
Expand Down Expand Up @@ -573,6 +573,7 @@ const sidebars = {
},
],
},
"api/token-api",
],
technologySidebar: [
"technology/architecture",
Expand Down

0 comments on commit 06024c2

Please sign in to comment.