API Introduction - 1tx Documentation

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

curl -H "x-api-key: your-api-key" \
  https://api.1tx.fi/api/v1/instruments

Response:

{
  "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

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

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

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

{
  "instrumentId": "0x...",
  "protocol": "Aave"
}

Paginated Response

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

Collection Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Aave"
  }
]

Error Response

{
  "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

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

Rate Limiting

API requests 1tx rate limited:

// 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:

# 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:

# 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:

# Sort by APY descending
?sort=apy:desc

# Sort by TVL ascending
?sort=tvl:asc

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

Next Steps

Instruments API

Query DeFi instruments

Integration Guide

Choose your integration model

Use Cases

See example implementations

​Overview

​Base URL

​Quick Start

​Make Your First Request

​Build a Buy Calldata Bundle

​Using TypeScript/JavaScript

​Using Python

​Response Format

​Single Resource Response

​Paginated Response

​Collection Response

​Error Response

​Error Codes

​Rate Limiting

​Pagination

​Filtering

​Sorting

​Next Steps

Instruments API

Integration Guide

Use Cases

Overview

Base URL

Quick Start

Make Your First Request

Build a Buy Calldata Bundle

Using TypeScript/JavaScript

Using Python

Response Format

Single Resource Response

Paginated Response

Collection Response

Error Response

Error Codes

Rate Limiting

Pagination

Filtering

Sorting

Next Steps