Agglayer SDK

Overview

The Agglayer SDK is a comprehensive TypeScript library that provides seamless integration with the Agglayer ecosystem. It combines the power of ARC API route aggregation with direct blockchain operations, enabling developers to build sophisticated cross-chain applications with minimal complexity.

Key Innovation:

• Multi-Bridge Routes: Access aggregated routes from Agglayer Bridge + LiFi Bridge through ARC API
• Native Bridge: Direct interaction with Agglayer bridge contracts for maximum control
• TypeScript-First: Full type safety with intelligent defaults and zero-config setup
• Production Ready: Enterprise-grade error handling and monitoring capabilities

What You Can Build

With the Agglayer SDK, you can create powerful cross-chain applications that leverage the best of both worlds:

• Cross-Chain DeFi Platforms: Build lending protocols, DEXes, and yield farming applications that seamlessly operate across multiple chains with optimal routing
• Multi-Chain Gaming Ecosystems: Create games where assets, achievements, and progress flow effortlessly between different blockchain networks
• Unified Wallet Applications: Develop wallet interfaces that provide users with the best routes for any cross-chain operation, automatically comparing costs and execution times
• Enterprise Bridge Solutions: Build scalable applications that handle high-volume cross-chain operations with comprehensive monitoring and error recovery

Two Powerful Approaches

The Agglayer SDK provides two complementary modules for different use cases:

Getting Started

Ready to start building with the Agglayer SDK?

Core Concepts

Understanding these fundamentals will help you make the most of the Agglayer SDK.

What is ARC API?

The Agglayer Route Consolidator (ARC) API aggregates bridge routes from multiple providers (Agglayer Bridge + LiFi) into a single interface. It automatically finds the best routes by comparing cost, speed, and output amounts across all available bridges, eliminating the need to integrate with each provider separately.

Chain ID vs Network ID

Chain ID is the standard blockchain identifier (e.g., Ethereum = 1, Base = 8453). Network ID is Agglayer's internal identifier for bridge contracts (e.g., Ethereum = 0, Katana = 20). Multi-Bridge Routes uses Chain IDs for route discovery, while Native Bridge uses Network IDs for direct contract interactions.

Transaction Building vs Execution

The SDK builds unsigned transactions with proper call data and gas estimates, but you're responsible for signing and broadcasting them to the blockchain using your wallet client (e.g., ethers.js, viem, or browser wallets). This design keeps your private keys secure by never exposing them to the SDK.

Token Approval Requirements

Before bridging ERC20 tokens, you must approve the bridge contract to spend your tokens. The SDK provides methods to check current allowances and build approval transactions. Native currency (ETH, POL) doesn't require approval since it's sent directly with the transaction value.

Development Path

The Agglayer SDK supports a complete development lifecycle:

Local Development

Start with AggSandbox for rapid prototyping and testing. The Native Bridge module integrates seamlessly with AggSandbox's local blockchain environment, providing instant feedback and comprehensive debugging.

Testnet Testing

Use Native Bridge on Sepolia and other testnets to validate your integration with real network conditions, gas costs, and timing without risking mainnet funds.

Production Deployment

Deploy with confidence using both Multi-Bridge Routes for optimal user experience and Native Bridge for direct control over bridge operations.

Why Choose Agglayer SDK?

Unified Route Access

The SDK is the only library that provides access to ARC API route aggregation, LiFi routes to give users the best possible cross-chain experience.

Developer Experience

• Zero Configuration: Intelligent defaults get you started immediately
• Full TypeScript Support: Complete type safety with comprehensive interfaces
• Modular Architecture: Use only the components you need
• Extensive Examples: Working code examples for every use case

Production Ready

• Battle Tested: Built on proven Agglayer infrastructure
• Comprehensive Error Handling: Robust error recovery and retry mechanisms
• Performance Optimized: Efficient API usage and blockchain interactions
• Monitoring Ready: Built-in support for transaction tracking and status monitoring

Architecture Overview

graph TB
    subgraph "Your Application"
        UI[User Interface]
        Logic[Business Logic]
    end
    
    subgraph "Agglayer SDK"
        MBR[Multi-Bridge Routes<br/>ARC API Integration]
        ANR[Agglayer Native Bridge<br/>Direct Blockchain]
    end
    
    subgraph "Agglayer Ecosystem"
        ARC[ARC API<br/>Route Aggregator]
        AB[Agglayer Bridge]
        LiFi[LiFi Bridge]
        BC[Bridge Contracts]
    end
    
    UI --> Logic
    Logic --> MBR
    Logic --> ANR
    MBR --> ARC
    ARC --> AB
    ARC --> LiFi
    ANR --> BC
    BC --> AB
    
    style MBR fill:#e3f2fd
    style ANR fill:#e8f5e8
    style ARC fill:#fff3e0

The SDK provides two complementary approaches: Multi-Bridge Routes for route aggregation and optimization, and Native Bridge for direct blockchain control.

Quick Example

Here's how simple it is to discover and execute cross-chain routes:

import { AggLayerSDK, SDK_MODES } from '@agglayer/sdk';

// Initialize with zero configuration
const sdk = new AggLayerSDK();

// Multi-Bridge Routes: Find optimal route
const core = sdk.getCore();
const routes = await core.getRoutes({
  fromChainId: 8453, // Base
  toChainId: 747474, // Katana
  fromTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  toTokenAddress: '0x203a662b0bd271a6ed5a60edfbd04bfce608fd36',
  amount: '1000000000', // 1000 USDC
  fromAddress: '0xYourAddress',
});

// Build executable transaction
const transaction = await core.getUnsignedTransaction(routes[0]);
// Ready to sign and execute!

Reference