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
Calldata Building: Build and simulate the call bundle your own account signs
Cross-Chain: Build a CCTP V2 source burn your own account redeems on the far side

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 Deposit Calldata Bundle

curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments/0x0000a4b194d4938ed6aab5bdbac7ca4b622f3639b1bca1b8b9c3271403d3b1b5/calldata?action=deposit&account=0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE&amount=2200000"

This returns the ordered calls the account signs and sends, already simulated at a pinned block. See the Calldata API.

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 is endpoint-specific. Market-data and calldata endpoints take x-api-key. Wallet-user-scoped endpoints, such as the portfolio routes, accept either x-api-key or 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

List endpoints page with limit and offset:

# Second page of 20
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?limit=20&offset=20"

limit (default: 20, max: 100)
offset (default: 0)

The pagination block in the response carries total and hasMore.

Filtering and sorting

# By protocol and chain
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?protocol=Aave&chainId=8453"

# Highest APY first
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?sortBy=apy&sortOrder=desc"

# Rank on yield that has held up, not this week's incentive
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments?enrich=true&tier=Core&maxCv=0.2&minHistoryDays=90&sortBy=apy&sortOrder=desc"

Sorting takes sortBy (apy, tvl, createdAt, cv, rewardShare, historyDays) and sortOrder (asc, desc) — one field at a time. See the Instruments API for every filter.

Next Steps

Instruments API

Query DeFi instruments

Integration Guide

Choose your integration model

Calldata API

Build the bundle to sign

​Overview

​Base URL

​Quick Start

​Make Your First Request

​Build a Deposit Calldata Bundle

​Using TypeScript/JavaScript

​Using Python

​Response Format

​Single Resource Response

​Paginated Response

​Collection Response

​Error Response

​Error Codes

​Rate Limiting

​Pagination

​Filtering and sorting

​Next Steps

Instruments API

Integration Guide

Calldata API

Overview

Base URL

Quick Start

Make Your First Request

Build a Deposit Calldata Bundle

Using TypeScript/JavaScript

Using Python

Response Format

Single Resource Response

Paginated Response

Collection Response

Error Response

Error Codes

Rate Limiting

Pagination

Filtering and sorting

Next Steps