Quickstart guide

This guide walks you through the 1inch Token API with Python and the requests library. You will search for tokens, look up token metadata, and read a chain's token list.

Every request in this guide uses v1.7, the recommended version. See Supported chains and versions for the chains each version covers.

Prerequisites

Python

Install Python if you do not have it, following the official instructions.

Requests library

The script makes HTTP requests with the requests library. Install it:

Bash
1
pip install requests

API key

Create an API key in the 1inch Business Portal and store it as an environment variable. Replace your_api_key with your key:

Bash
1
export API_KEY=your_api_key

Reload your shell configuration to pick it up:

Bash
1
source ~/.zshrc  # zsh; use ~/.bashrc for bash

Rate limits

The script pauses one second between calls so it stays inside the default rate limit. time is part of Python's standard library, so there is nothing to install.

Step 1: Set up the request helper

Start with the imports, the base URL and the authorization header. Every request below uses them.

Python
1
2
3
4
5
6
7
8
9
10
11
import os
import time

import requests

API_KEY = os.getenv("API_KEY")
BASE_URL = "https://api.1inch.com/token"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "accept": "application/json",
}

Step 2: Search for tokens on a chain

GET /v1.7/{chainId}/search matches a token name, symbol or address. Pass limit to cap the results (1–100).

Python
1
2
3
4
5
6
7
8
def search_tokens(chain_id, query, limit=10):
    response = requests.get(
        f"{BASE_URL}/v1.7/{chain_id}/search",
        headers=HEADERS,
        params={"query": query, "limit": limit},
    )
    response.raise_for_status()
    return response.json()

Step 3: Get token metadata

Use GET /v1.7/{chainId}/custom/{address} for one token, and GET /v1.7/{chainId}/custom?addresses= for several in one call. The many-token form takes an addresses query parameter, not a comma-separated path.

Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
def get_token(chain_id, address):
    response = requests.get(
        f"{BASE_URL}/v1.7/{chain_id}/custom/{address}",
        headers=HEADERS,
    )
    response.raise_for_status()
    return response.json()


def get_tokens(chain_id, addresses):
    response = requests.get(
        f"{BASE_URL}/v1.7/{chain_id}/custom",
        headers=HEADERS,
        params={"addresses": addresses},
    )
    response.raise_for_status()
    return response.json()

Step 4: Read a chain's token list

GET /v1.7/{chainId} returns every token 1inch knows on that chain. GET /v1.7/{chainId}/token-list returns the same set in Uniswap token list format, which wallets and aggregators can consume directly.

Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
def get_all_tokens(chain_id, provider="1inch"):
    response = requests.get(
        f"{BASE_URL}/v1.7/{chain_id}",
        headers=HEADERS,
        params={"provider": provider},
    )
    response.raise_for_status()
    return response.json()


def get_token_list(chain_id, provider="1inch"):
    response = requests.get(
        f"{BASE_URL}/v1.7/{chain_id}/token-list",
        headers=HEADERS,
        params={"provider": provider},
    )
    response.raise_for_status()
    return response.json()

Step 5: Run the calls

Python
1
2
3
4
5
6
7
8
9
10
11
12
13
if __name__ == "__main__":
    chain_id = 1  # Ethereum

    print(search_tokens(chain_id, "1inch"))
    time.sleep(1)

    print(get_token(chain_id, "0x111111111117dc0aa78b770fa6a738034120c302"))
    time.sleep(1)

    print(get_tokens(chain_id, ["0x111111111117dc0aa78b770fa6a738034120c302"]))
    time.sleep(1)

    print(get_token_list(chain_id))

Next steps

Did you find what you need?