Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Alpha Token API #928

Merged
merged 21 commits into from
Jan 27, 2025
Merged
Show file tree
Hide file tree
Changes from 18 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/api/index.mdx → docs/api/reference/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Linea supports the standard Ethereum JSON-RPC API methods, meaning the developer experience is
identical to building on Ethereum itself. However, some methods differ to Ethereum — find them in
the [reference section](./reference/eth-sendrawtransaction.mdx).
identical to building on Ethereum itself. However, some methods differ to Ethereum, and are covered
in this section.

:::info
View the full list of Linea methods in the
Expand All @@ -20,13 +20,13 @@ View the full list of Linea methods in the
You must connect to an RPC endpoint when making calls to the Linea blockchain. Use one or more of the
following options:

- **Run your own node**: Either [run your own node by setting it up yourself](../get-started/how-to/run-a-node/index.mdx), or
[use a node provider](../get-started/tooling/node-providers/index.mdx).
We recommend running [Linea Besu](../get-started/how-to/run-a-node/linea-besu.mdx) if you want to run a node yourself and interact with the
- **Run your own node**: Either [run your own node by setting it up yourself](../../get-started/how-to/run-a-node/index.mdx), or
[use a node provider](../../get-started/tooling/node-providers/index.mdx).
We recommend running [Linea Besu](../../get-started/how-to/run-a-node/linea-besu.mdx) if you want to run a node yourself and interact with the
blockchain.
- **Connect to a private RPC endpoint**: [Connect to a blockchain infrastructure provider](../get-started/tooling/node-providers/index.mdx#private-rpc-endpoints)
- **Connect to a private RPC endpoint**: [Connect to a blockchain infrastructure provider](../../get-started/tooling/node-providers/index.mdx#private-rpc-endpoints)
such as Infura or Alchemy. Multiple providers offer free tier access.
- **Use a public endpoint**: [Public endpoints](../get-started/tooling/node-providers/index.mdx#public-rpc-endpoints) are
- **Use a public endpoint**: [Public endpoints](../../get-started/tooling/node-providers/index.mdx#public-rpc-endpoints) are
free to use but are rate limited and not suitable for production environments.

## Make calls
Expand All @@ -37,7 +37,7 @@ the endpoint with whichever endpoint you prefer.
In the examples, replace `<YOUR-API-KEY>` with your actual Infura API key.

:::info
View the [list of node providers](../get-started/tooling/node-providers/index.mdx) if you require an endpoint.
View the [list of node providers](../../get-started/tooling/node-providers/index.mdx) if you require an endpoint.
:::


Expand Down
98 changes: 98 additions & 0 deletions docs/api/token-api/overview.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
title: Token API
image: /img/socialCards/token-api.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 activity on Linea.

:::warning[Alpha Version]
Linea's Token API is in alpha version and subject to breaking changes.
We recommend using it for testing and development purposes only.
We welcome your feedback on our [Discord](https://discord.com/invite/linea)
in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024) channel.
:::

## Key features

### Token data
- Complete list of available tokens on Linea
- Detailed token metadata (name, symbol, decimals, logo)
- Current and historical prices
- Trading statistics (buy/sell counts)

### Market analytics
- Most traded tokens in the last 24h
- Top gainers and losers (price variation)
- Recently bonded tokens
- Price movement tracking

### Use cases
- Automated trading bots
- Token monitoring dashboards
- Onchain data analysis
- DeFi application integration
- Wallet and transaction tracking

## Data sources

Data is collected and updated from multiple sources:

### Primary sources
- Onchain data (smart contract states)
- [CoinGecko](https://www.coingecko.com/en/api)
- MetaMask Token & Price API
- [Pond.fun](https://pond.fun/)
- [Dune Analytics](https://dune.com/)

### Update frequencies
- Token detection and metadata: every two hours
- Historical prices: hourly
- Current prices: every five minutes

## API documentation

The complete API documentation is available in our [Swagger UI](https://token-api.devnet.linea.build/docs).

## Usage examples

### Simple token price bot

```typescript
async function monitorPriceChange(contractAddress: string, threshold: number) {
const BASE_URL = "https://token-api.devnet.linea.build";
const { currentPrice: initialPrice } = await fetch(`${BASE_URL}/tokens/${contractAddress}`).then(r => r.json());

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

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**
- Alpha version has strict rate limits per IP:
- Two requests per second
- 60 requests per minute
- Cache static data
- Implement backoff strategies

2. **Error handling**
- Check HTTP status codes
- Implement retry with exponential backoff
- Validate token addresses

3. **Performance and security**
- (Not available yet) Use pagination for large lists
- Use local caching when appropriate
- Validate and sanitize all inputs

## Support

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.
2 changes: 1 addition & 1 deletion docs/get-started/build/ethereum-differences.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -102,4 +102,4 @@ The point evaluation precompile was introduced in [EIP-4844](https://eips.ethere
## JSON RPC API

Linea uses the standard Ethereum JSON RPC API methods. However, in a few cases, methods differ from
those on Ethereum. These methods are documented in the [reference section](../../api/index.mdx).
those on Ethereum. These methods are documented in the [reference section](../../api/reference/index.mdx).
4 changes: 2 additions & 2 deletions docs/get-started/how-to/run-a-node/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This section guides you through running a Linea node using various compatible Et

:::info important
While Linea supports multiple clients, only Linea Besu currently allows you to access Linea-specific
features, such as using [Linea methods](../../../api/index.mdx) (for example, `linea_estimateGas`)
features, such as using [Linea methods](../../../api/reference/index.mdx) (for example, `linea_estimateGas`)
or calling methods using the `finalized` tag.

Linea Besu is recommended for infrastructure providers and operators who intend to run a Linea
Expand Down Expand Up @@ -41,7 +41,7 @@ to Linea-specific features.
</tr>
<tr>
<td>[Linea Besu](./linea-besu.mdx)</td>
<td>Besu client with plugins that implement Linea-specific features, such as <a href="../../../api/index.mdx">API methods</a> and <a href="../finalized-block.mdx">finalized</a> tag.</td>
<td>Besu client with plugins that implement Linea-specific features, such as <a href="../../../api/reference/index.mdx">API methods</a> and <a href="../finalized-block.mdx">finalized</a> tag.</td>
<td>✅</td>
</tr>
<tr>
Expand Down
3 changes: 2 additions & 1 deletion docs/get-started/tooling/cross-chain/ccip.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: Chainlink Cross-Chain Interoperability Protocol (CCIP)
sidebar_label: Chainlink CCIP
image: /img/socialCards/chainlink-cross-chain-interoperability-protocol-ccip.jpg
---

Chainlink CCIP is a blockchain interoperability protocol that enables developers to build secure
Expand All @@ -22,4 +23,4 @@ CCIP fees. [See the token contracts for LINK on Linea](https://docs.chain.link/r
- [Linea CCIP directory](https://docs.chain.link/ccip/directory/mainnet/chain/ethereum-mainnet-linea-1)
- [LINK token contracts on Linea](https://docs.chain.link/resources/link-token-contracts#linea)
- [Chainlink Builder's Quick Links](https://docs.chain.link/builders-quick-links), showing all
Chainlink services available on Linea
Chainlink services available on Linea
15 changes: 13 additions & 2 deletions docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,17 @@ const config = {
},
},
],
[
"redocusaurus",
{
specs: [
{
spec: "https://token-api.devnet.linea.build/docs-yaml",
route: "api/token-api/reference",
},
],
},
],
],

themeConfig:
Expand Down Expand Up @@ -141,9 +152,9 @@ const config = {
},
{
type: "doc",
docId: "api/index",
docId: "api/linea-smart-contracts/linearollup",
position: "left",
label: "API & SDK",
label: "APIs & SDK",
},
{
type: "doc",
Expand Down
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"
}
]
}

Loading
Loading