Integration Overview - 1tx Documentation

Integration Models

1tx supports three integration patterns to fit different use cases and technical requirements:

Model 1: Direct Blockchain Integration

Best For

DeFi protocols, wallets, and dApps that want full control over transactions

Overview

Integration: Direct smart contract calls via Web3 library
Custody: User’s self-custody wallet (MetaMask, Coinbase Wallet, etc.)
Automation: None - user signs every transaction
Complexity: Medium

Key Features

Full Control

Complete control over transaction parameters and execution

Self-Custody

Users maintain full custody of their assets

No API Keys

No need for API authentication

On-Chain Only

All logic executed on-chain

Use Cases

DeFi protocols accepting deposits in any token
Wallet applications offering yield strategies
dApps with existing Web3 integration
Smart contract-based automated strategies

Getting Started

Install Web3 Library

npm install viem wagmi

Connect User Wallet

import { useConnect } from 'wagmi';

const { connect, connectors } = useConnect();
connect({ connector: connectors[0] });

Call Smart Contracts

// Execute a router buy.
// buy(instrumentId, amount, minDepositedAmount, fastTransfer, maxFee, referralFeeBps, referralWallet)
await d1txRouter.write.buy([
  instrumentId,
  amount,
  0n,
  false,
  0n,
  0,                                              // referralFeeBps (0-500)
  '0x0000000000000000000000000000000000000000',   // referralWallet
]);

Quickstart

Start from the on-chain quickstart example

Direct Contract Cookbook

See viem recipes for approve, buy, sell, and cross-chain monitoring

Model 2: API + External Wallets

Best For

Exchanges, platforms, and services with existing wallet infrastructure

Overview

Integration: REST API for discovery + smart contracts for execution
Custody: User’s self-custody wallet
Automation: None - user must be online to sign
Complexity: Medium-High

Key Features

Instrument Discovery

Query available instruments via API

Rich Metadata

Access APY, TVL, historical data

Self-Custody

Users maintain control of assets

Hybrid Approach

Best of API and blockchain

Use Cases

Centralized exchanges offering DeFi yield
Investment platforms with portfolio management
Financial advisors providing DeFi access
Applications with custom UX requirements

Getting Started

Get API Key

Query Instruments

const response = await fetch('https://api.1tx.fi/api/v1/instruments', {
  headers: { 'x-api-key': apiKey },
});
const instruments = await response.json();

Build the Transaction Bundle

const selectedInstrument = instruments.data[0];

const buildResponse = await fetch('https://api.1tx.fi/api/v1/transactions/buy', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwt}`,
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userAddress,
    instrumentId: selectedInstrument.instrumentId,
    amountUsdc: '1000.00',
  }),
});

const bundle = await buildResponse.json();
console.log(bundle.transactions);

Execute and Monitor

Send the returned transactions in order with the user’s wallet. If bundle.isCrossChain is true, poll:

const relay = await fetch(
  `https://api.1tx.fi/api/v1/cctp/relay/tx/${sourceTxHash}`,
  { headers: { 'x-api-key': apiKey } }
);

until the returned status becomes success or failed.

API Reference

See the REST API endpoints and payloads

API Cookbook

Follow end-to-end API recipes for bundle building and cross-chain tracking

Model 3: API + Embedded Wallets

Best For

AI agents, robo-advisors, fintechs, and automated yield strategies

Overview

Integration: REST API + Privy embedded wallets
Custody: User (via non-custodial embedded wallet)
Automation: Yes - session keys enable automated trading
Complexity: High

Key Features

Full Automation

Execute trades 24/7 without user interaction

Session Keys

Time-limited, amount-limited permissions

Non-Custodial

User owns the private key (via Privy)

Seamless UX

No wallet installation required

Use Cases

AI-powered yield optimizers
Robo-advisors with automated rebalancing
Fintechs offering DeFi savings accounts
Telegram/Discord bots with trading capabilities
Recurring DCA (Dollar Cost Averaging) strategies

Getting Started

Set Up Privy

npm install @privy-io/react-auth

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

<PrivyProvider appId="your-privy-app-id">
  <YourApp />
</PrivyProvider>

Create Embedded Wallet

const { createWallet } = usePrivy();

// Create wallet for user
const wallet = await createWallet();
console.log('Wallet address:', wallet.address);

Create Session Key

const { createSessionKey } = usePrivy();

// Allow automated trading up to 10k USDC for 24 hours
await createSessionKey({
  maxAmount: parseEther("10000"),
  expiry: Date.now() + 86400000, // 24 hours
});

Automate Deposits

// Your backend can now execute trades automatically
async function autoOptimizeYield(userId: string) {
  const bestInstrument = await findBestYield();

  await depositToInstrument(
    bestInstrument.id,
    amount,
    { sessionKey: await getSessionKey(userId) }
  );
}

AI Agent Use Case

See an embedded-wallet oriented integration path

Comparison Matrix

Feature	Model 1: Direct	Model 2: API + Wallet	Model 3: Embedded
Control	Full	Full	Delegated
Automation	❌ No	❌ No	✅ Yes
Custody	Self-custody	Self-custody	Non-custodial
User Experience	Wallet required	Wallet required	No wallet needed
Complexity	Medium	Medium-High	High
Instrument Discovery	Manual	✅ API	✅ API
Historical Data	❌ No	✅ API	✅ API
24/7 Trading	❌ No	❌ No	✅ Yes
Best For	dApps, wallets	Exchanges, platforms	AI agents, robo-advisors

Architecture Decision Tree

Do you need automated trading?

Yes → Model 3: Embedded WalletsNo → Continue to next question

Do you need instrument discovery or analytics?

Yes → Model 2: API + External WalletsNo → Model 1: Direct Blockchain

Do you have existing wallet infrastructure?

Yes → Model 2: API + External WalletsNo → Consider Model 3 for better UX

Is your application a dApp or protocol?

Yes → Model 1: Direct BlockchainNo → Model 2 or 3 depending on automation needs

Hybrid Approaches

You can combine multiple models:

Model 1 + 2: Direct + API

Use API for discovery and metadata, direct contracts for execution:

// 1. Query instruments via API
const instruments = await api.instruments.list({ minApy: 5 });

// 2. Execute buy via 1tx Router
await d1txRouter.write.buy([
  instruments[0].instrumentId,
  amount,
  0n,
  false,
  0n,
  0,                                              // referralFeeBps
  '0x0000000000000000000000000000000000000000',   // referralWallet
]);

Benefits: Rich discovery + full control

Model 2 + 3: API + Both Wallet Types

Support both external and embedded wallets:

function useWallet() {
  const { address: externalAddress } = useAccount(); // Wagmi
  const { user } = usePrivy(); // Privy

  const wallet = externalAddress || user?.wallet?.address;

  return { wallet, type: externalAddress ? 'external' : 'embedded' };
}

Benefits: Flexibility for different user types

Next Steps

How It Works

Understand the transaction flow

API Reference

Explore API endpoints

Use Cases

View integration examples

Core Concepts

Learn the fundamentals

​Integration Models

​Model 1: Direct Blockchain Integration

Best For

​Overview

​Key Features

Full Control

Self-Custody

No API Keys

On-Chain Only

​Use Cases

​Getting Started

Quickstart

Direct Contract Cookbook

​Model 2: API + External Wallets

Best For

​Overview

​Key Features

Instrument Discovery

Rich Metadata

Self-Custody

Hybrid Approach

​Use Cases

​Getting Started

API Reference

API Cookbook

​Model 3: API + Embedded Wallets

Best For

​Overview

​Key Features

Full Automation

Session Keys

Non-Custodial

Seamless UX

​Use Cases

​Getting Started

AI Agent Use Case

​Comparison Matrix

​Architecture Decision Tree

​Hybrid Approaches

​Next Steps

How It Works

API Reference

Use Cases

Core Concepts

Integration Models

Model 1: Direct Blockchain Integration

Overview

Key Features

Use Cases

Getting Started

Model 2: API + External Wallets

Overview

Key Features

Use Cases

Getting Started

Model 3: API + Embedded Wallets

Overview

Key Features

Use Cases

Getting Started

Comparison Matrix

Architecture Decision Tree

Hybrid Approaches

Next Steps