Skip to main content

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

1

Install Web3 Library

npm install viem wagmi
2

Connect User Wallet

import { useConnect } from 'wagmi';

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

Call Smart Contracts

// Execute a router buy.
// buy(instrumentId, amount, minDepositedAmount, fastTransfer, maxFee)
await d1txRouter.write.buy([
  instrumentId,
  amount,
  0n,
  false,
  0n,
]);

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

1

Get API Key

2

Query Instruments

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

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);
4

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

1

Set Up Privy

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

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

Create Embedded Wallet

const { createWallet } = usePrivy();

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

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
});
4

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

FeatureModel 1: DirectModel 2: API + WalletModel 3: Embedded
ControlFullFullDelegated
Automation❌ No❌ No✅ Yes
CustodySelf-custodySelf-custodyNon-custodial
User ExperienceWallet requiredWallet requiredNo wallet needed
ComplexityMediumMedium-HighHigh
Instrument DiscoveryManual✅ API✅ API
Historical Data❌ No✅ API✅ API
24/7 Trading❌ No❌ No✅ Yes
Best FordApps, walletsExchanges, platformsAI agents, robo-advisors

Architecture Decision Tree

1

Do you need automated trading?

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

Do you need instrument discovery or analytics?

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

Do you have existing wallet infrastructure?

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

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:
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,
]);
Benefits: Rich discovery + full control
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