Quickstart

Setup your development environment

Follow these steps to integrate 1tx into your application.

Option 1: Direct Smart Contract Integration

Perfect for DeFi protocols and wallets that want to interact directly with our contracts.

Install Dependencies

Install the necessary packages:

npm install viem wagmi
# or
yarn add viem wagmi

Configure Contract Addresses

Import the deployed contract addresses (Base Mainnet):

const ONETX_ROUTER = "0xbFdd5bEdC0cB9B8795A93C2a1fB634012C8F99bC";
const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";

Make Your First Buy

Execute a buy into Aave USDC using the 1tx router:

import { parseUnits } from 'viem';

// Instrument ID for Aave USDC on Base
const AAVE_USDC_ID = "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b";
const amount = parseUnits("1000", 6); // 1000 USDC

// 1. Approve 1tx Router to spend your USDC
await usdc.write.approve([ONETX_ROUTER, amount]);

// 2. Execute buy via 1tx Router
// buy(instrumentId, amount, minDepositedAmount, fastTransfer, maxFee, referralFeeBps, referralWallet)
await d1txRouter.write.buy([
  AAVE_USDC_ID,
  amount,
  0n,
  false,
  0n,
  0,                                              // referralFeeBps (0-500, e.g. 25 = 0.25%)
  '0x0000000000000000000000000000000000000000',   // referralWallet (zero address = no referral)
]);

Use minDepositedAmount to enforce your minimum acceptable output. For same-asset deposits such as Aave USDC, 0n is fine because no internal swap is needed.To earn a referral fee, pass referralFeeBps (up to 500 = 5%) and a non-zero referralWallet. The fee is taken from the input USDC before swap/deposit.

The deployment set in 1tx-contracts/docs/deployments.md uses SwapDepositRouter.buy() and sell() on Base, Arbitrum, and Unichain.

Contract Addresses

Need the full multi-chain deployment set? See Contract Addresses for Base, Arbitrum, and Unichain router, registry, adapter, and bridge addresses.

Option 2: REST API Integration

Perfect for applications that need instrument discovery, calldata generation, and cross-chain execution tracking.

Get Your API Key

Make Your First Request

Fetch all available instruments:

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

Query Specific Instrument

Get details for a specific instrument:

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

Build Buy Calldata

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"
  }'

Send the returned transactions in order with the user’s wallet.

Monitor Cross-Chain Completion

After the source transaction confirms, poll relay status by source tx hash:

curl "https://api.1tx.fi/api/v1/cctp/relay/tx/0xSourceTxHash"

A brief 404 Job not found immediately after source-chain confirmation is expected while the bridge webhook is being ingested.

Option 3: Embedded Wallet Integration

Perfect for AI agents and robo-advisors that need automated trading.

Install Privy SDK

npm install @privy-io/react-auth wagmi viem

Configure Privy Provider

import { PrivyProvider } from '@privy-io/react-auth';

<PrivyProvider
  appId="your-privy-app-id"
  config={{
    embeddedWallets: {
      createOnLogin: 'all-users',
    },
  }}
>
  <YourApp />
</PrivyProvider>

Create Session Keys

Enable automated trading within limits:

import { usePrivy } from '@privy-io/react-auth';

const { createSessionKey } = usePrivy();

// Create session key with limits
await createSessionKey({
  maxAmount: parseEther("10000"), // Max 10k USDC
  expiry: Date.now() + 86400000, // 24 hours
});

Example Use Cases

Wallet Integration

Let users deposit to any protocol from any token

AI Agent

Build autonomous yield optimization strategies

Exchange

Offer institutional DeFi access to your users

DeFi Protocol

Accept deposits in any token, not just your native token

Next Steps

Read How It Works

Understand the architecture in detail

Core Concepts

Learn about universal instrument IDs

View API Docs

Explore all available endpoints

Integration Patterns

Choose the best integration for your use case

Get Started

Core Concepts

Integration Guides

Use Cases

Setup your development environment

Option 1: Direct Smart Contract Integration

Contract Addresses

Option 2: REST API Integration

Option 3: Embedded Wallet Integration

Example Use Cases

Wallet Integration

AI Agent

Exchange

DeFi Protocol

Next Steps

Read How It Works

Core Concepts

View API Docs

Integration Patterns

​Setup your development environment

​Option 1: Direct Smart Contract Integration

​Contract Addresses

​Option 2: REST API Integration

​Option 3: Embedded Wallet Integration

​Example Use Cases

Wallet Integration

AI Agent

Exchange

DeFi Protocol

​Next Steps

Read How It Works

Core Concepts

View API Docs

Integration Patterns

Setup your development environment

Option 1: Direct Smart Contract Integration

Contract Addresses

Option 2: REST API Integration

Option 3: Embedded Wallet Integration

Example Use Cases

Next Steps