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](./introduction) for the chains each version covers.

## Prerequisites

### Python

Install Python if you do not have it, following the [official instructions](https://www.python.org/).

### Requests library

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

```bash
pip install requests
```

### API key

Create an API key in the [1inch Business Portal](/login) and store it as an environment variable. Replace `your_api_key` with your key:

```bash
export API_KEY=your_api_key
```

Reload your shell configuration to pick it up:

```bash
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
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
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
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
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
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

- [Token API reference](./methods) lists every v1.7 endpoint with its parameters and responses.
- [Supported chains and versions](./introduction) shows which chains each version covers.
