Skip to main content

​
Overview

The 1tx REST API provides programmatic access to:
  • Instrument Discovery: Query all available DeFi instruments
  • Metrics & Analytics: Historical APY, TVL, and performance data
  • 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 CodeError CodeDescription
400BAD_REQUESTInvalid request parameters
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn’t have required permissions
404NOT_FOUNDResource not found
429RATE_LIMIT_EXCEEDEDToo many requests
500INTERNAL_ERRORServer 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