> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1tx.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Get started with the 1tx REST API

## Overview

The 1tx REST API provides programmatic access to:

* **Instrument Discovery:** Query all available DeFi instruments
* **Metrics & Analytics:** Historical APY, TVL, and performance data
* **Portfolio Analysis:** Score allocations, compare portfolio changes, and simulate historical yield
* **Protocol Information:** Supported protocols and their markets
* **Transaction Building:** Build router calldata bundles for buys and sells
* **Cross-Chain Monitoring:** Estimate CCTP fees and track bridge execution by source tx hash

## Base URL

```
https://api.1tx.fi/api/v1
```

## Quick Start

### Make Your First Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  https://api.1tx.fi/api/v1/instruments
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
      "protocol": "Aave",
      "protocolInfo": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Aave",
        "version": 3,
        "displayName": "Aave V3",
        "icon": "aave",
        "docsUrl": "https://docs.aave.com",
        "deprecated": false
      },
      "chainId": 8453,
      "protocolAddress": "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",
      "marketId": "0x000000000000000000000000833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "adapterAddress": "0xBACC8882E2a9f5a67570E1BC10d87062dB68dfDd",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenSymbol": "USDC",
      "yieldTokenAddress": "0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB",
      "yieldTokenSymbol": "aBasUSDC",
      "description": "Aave V3 USDC lending pool on Base",
      "symbol": "USDC",
      "currentApy": 5.2,
      "tvl": 1250000000,
      "lastSyncedAt": "2024-01-15T14:30:00.000Z",
      "isActive": true,
      "isStablecoin": true,
      "assetCategory": "USD",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 18,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
```

### Build a Buy Calldata Bundle

```bash theme={null}
curl -X POST "https://api.1tx.fi/api/v1/transactions/buy" \
  -H "Authorization: Bearer <your_jwt>" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE",
    "instrumentId": "0x0000a4b194d4938ed6aab5bdbac7ca4b622f3639b1bca1b8b9c3271403d3b1b5",
    "amountUsdc": "2.20"
  }'
```

This returns the ordered transaction bundle the user wallet should sign and send.

### Using TypeScript/JavaScript

```typescript theme={null}
const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.1tx.fi/api/v1';

async function getInstruments() {
  const response = await fetch(`${BASE_URL}/instruments`, {
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data;
}

// Usage
const instruments = await getInstruments();
console.log(`Found ${instruments.pagination.total} instruments`);
```

### Using Python

```python theme={null}
import requests

API_KEY = 'your-api-key'
BASE_URL = 'https://api.1tx.fi/api/v1'

def get_instruments():
    headers = {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
    }

    response = requests.get(f'{BASE_URL}/instruments', headers=headers)
    response.raise_for_status()

    return response.json()

# Usage
instruments = get_instruments()
print(f"Found {instruments['pagination']['total']} instruments")
```

## Response Format

Responses are endpoint-specific. The most common shapes in this API are:

### Single Resource Response

```json theme={null}
{
  "instrumentId": "0x...",
  "protocol": "Aave"
}
```

### Paginated Response

```json theme={null}
{
  "data": [
    // Array of items
  ],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}
```

### Collection Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Aave"
  }
]
```

### Error Response

```json theme={null}
{
  "statusCode": 404,
  "message": "Instrument with ID 0x... not found",
  "timestamp": "2024-01-15T14:30:00.000Z",
  "path": "/api/v1/instruments/0x..."
}
```

## Error Codes

| Status Code | Error Code            | Description                               |
| ----------- | --------------------- | ----------------------------------------- |
| 400         | `BAD_REQUEST`         | Invalid request parameters                |
| 401         | `UNAUTHORIZED`        | Missing or invalid API key                |
| 403         | `FORBIDDEN`           | API key doesn't have required permissions |
| 404         | `NOT_FOUND`           | Resource not found                        |
| 429         | `RATE_LIMIT_EXCEEDED` | Too many requests                         |
| 500         | `INTERNAL_ERROR`      | Server error                              |

<Note>
  Authentication requirements are endpoint-specific. Market-data endpoints use `x-api-key`. Transaction-building endpoints require both `x-api-key` and `Authorization: Bearer <jwt>`.
</Note>

## Rate Limiting

API requests 1tx rate limited:

```json theme={null}
// Rate limit headers included in every response
{
  "X-RateLimit-Limit": "10000",
  "X-RateLimit-Remaining": "9850",
  "X-RateLimit-Reset": "1642261200"
}
```

## Pagination

Most list endpoints support pagination:

```bash theme={null}
# Get page 2 with 20 items per page
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?page=2&limit=20"
```

**Parameters:**

* `page` (default: 1) - Page number
* `limit` (default: 10, max: 100) - Items per page

## Filtering

Filter instruments by various criteria:

```bash theme={null}
# Filter by protocol
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?protocol=Aave"

# Filter by minimum APY
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?minApy=5"

# Combine filters
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?protocol=Aave&minApy=5&sort=apy:desc"
```

## Sorting

Sort results using the `sort` parameter:

```bash theme={null}
# Sort by APY descending
?sort=apy:desc

# Sort by TVL ascending
?sort=tvl:asc

# Multiple sort fields
?sort=apy:desc,tvl:desc
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Instruments API" icon="fingerprint" href="/api-reference/endpoints/instruments">
    Query DeFi instruments
  </Card>

  <Card title="Integration Guide" icon="book" href="/integration/overview">
    Choose your integration model
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/use-cases/wallets">
    See example implementations
  </Card>
</CardGroup>