PolygonPolygon Telegram
AgglayerDeveloper ToolsAgglayer SDK

Installation

Install and configure the Agglayer SDK in your TypeScript or JavaScript project

Prerequisites

Before installing the Agglayer SDK, ensure you have the following:

System Requirements

RequirementVersionDescription
Node.js18.0.0+JavaScript runtime environment
npm8.0.0+Package manager (comes with Node.js)
TypeScript4.9.0+For TypeScript projects (recommended)

Verify Prerequisites

# Check Node.js version
node --version

# Check npm version
npm --version

# Check TypeScript version (if using TypeScript)
npx tsc --version

Installation

Using NPM

# Production (stable) - Coming Soon
npm install @agglayer/sdk

Basic Setup

TypeScript Project Setup

// src/index.ts
import { AggLayerSDK, SDK_MODES } from '@agglayer/sdk';

// Zero configuration - uses intelligent defaults
const sdk = new AggLayerSDK();

// Access Multi-Bridge Routes (ARC API)
const core = sdk.getCore();

// Or configure both modules
const fullSDK = new AggLayerSDK({
  mode: [SDK_MODES.CORE, SDK_MODES.NATIVE],
  core: {
    apiBaseUrl: 'https://arc-api.polygon.technology',
    apiTimeout: 30000,
  },
  native: {
    defaultNetwork: 1, // Ethereum mainnet
  },
});

const core = fullSDK.getCore();
const native = fullSDK.getNative();

JavaScript Project Setup

// src/index.js
const { AggLayerSDK, SDK_MODES } = require('@agglayer/sdk');

// Zero configuration setup
const sdk = new AggLayerSDK();

// Access modules
const core = sdk.getCore();

Environment Configuration

Environment Variables

Create a .env file for your configuration:

# Multi-Bridge Routes Configuration (ARC API)
ARC_API_BASE_URL=https://arc-api.polygon.technology
ARC_API_TIMEOUT=30000

# Native Bridge Configuration (RPC URLs)
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-api-key
KATANA_RPC_URL=https://rpc.katana.network
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your-api-key

# AggSandbox Local Configuration
AGGSANDBOX_L1_RPC_URL=http://localhost:8545
AGGSANDBOX_L2_RPC_URL=http://localhost:8546

# Development Configuration
NODE_ENV=development

# Optional: Additional API Services
TOKEN_LIST_API=https://api-polygon-tokens.polygon.technology/tokenlists/agglayer.tokenlist.json
BALANCE_API=https://balance-api-gcp.polygon.technology/mainnet/tokens

Configuration Examples

Local Configuration

For local development with AggSandbox:

// config/local.ts
import { AggLayerSDK, SDK_MODES } from '@agglayer/sdk';

export const localSDK = new AggLayerSDK({
  mode: [SDK_MODES.NATIVE],
  native: {
    defaultNetwork: 1, // L1 network in AggSandbox
    customRpcUrls: {
      1: process.env.AGGSANDBOX_L1_RPC_URL || 'http://localhost:8545',
      1101: process.env.AGGSANDBOX_L2_RPC_URL || 'http://localhost:8546',
    },
  },
});

// Note: Multi-Bridge Routes (CORE mode) not available locally
// Use Native Bridge for direct bridge contract interactions

Additional Environment Variables for Local Testing:

# Optional: For testing with known AggSandbox private keys
AGG_SANDBOX_PRIVATE_KEY=  # Can be found via `aggsandbox info` command

Important: SDK manual claiming doesn't work with AggSandbox due to API endpoint differences. Use AggSandbox's auto-claiming service for local testing.

Testnet Configuration

// config/development.ts
import { AggLayerSDK, SDK_MODES } from '@agglayer/sdk';

export const developmentSDK = new AggLayerSDK({
  mode: [SDK_MODES.CORE, SDK_MODES.NATIVE],
  core: {
    apiBaseUrl: process.env.ARC_API_BASE_URL || 'https://arc-api.polygon.technology',
    apiTimeout: 10000, // Shorter timeout for development
  },
  native: {
    defaultNetwork: 11155111, // Sepolia testnet
    customRpcUrls: {
      11155111: process.env.SEPOLIA_RPC_URL,
      747474: process.env.KATANA_RPC_URL,
    },
  },
});

Mainnet Configuration

// config/production.ts
import { AggLayerSDK, SDK_MODES } from '@agglayer/sdk';

export const productionSDK = new AggLayerSDK({
  mode: [SDK_MODES.CORE, SDK_MODES.NATIVE],
  core: {
    apiBaseUrl: 'https://arc-api.polygon.technology',
    apiTimeout: 30000,
  },
  native: {
    defaultNetwork: 1, // Ethereum mainnet
    customRpcUrls: {
      1: process.env.ETHEREUM_RPC_URL,
      747474: process.env.KATANA_RPC_URL,
    },
  },
});

Verification

Test Installation

Create a simple test file to verify everything is working:

// test-installation.ts
import { AggLayerSDK } from '@agglayer/sdk';

async function testInstallation() {
  try {
    // Test Multi-Bridge Routes
    const sdk = new AggLayerSDK();
    const core = sdk.getCore();
    
    console.log('🚀 Testing Agglayer SDK installation...');
    
    // Test ARC API connection
    const chains = await core.getAllChains();
    console.log(`✅ Multi-Bridge Routes: Found ${chains.chains.length} supported chains`);
    
    // Test Native Routes (if RPC configured)
    if (process.env.ETHEREUM_RPC_URL) {
      const nativeSDK = new AggLayerSDK({
        mode: ['NATIVE'],
        native: {
          defaultNetwork: 1,
          customRpcUrls: {
            1: process.env.ETHEREUM_RPC_URL,
          },
        },
      });
      
      const native = nativeSDK.getNative();
      const supportedNetworks = native.getSupportedNetworks();
      console.log(`✅ Native Bridge: ${supportedNetworks.length} networks configured`);
    }
    
    console.log('🎉 Installation verified successfully!');
    
  } catch (error) {
    console.error('❌ Installation test failed:', error);
    process.exit(1);
  }
}

testInstallation();

Run the test:

npx ts-node test-installation.ts

Expected output:

🚀 Testing Agglayer SDK installation...
✅ Multi-Bridge Routes: Found 15 supported chains
✅ Native Bridge: 2 networks configured
🎉 Installation verified successfully!

Module Selection

The SDK uses a modular architecture - choose the modules you need:

Multi-Bridge Routes Only

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

const sdk = new AggLayerSDK({
  mode: [SDK_MODES.CORE], // Only Multi-Bridge Routes
  core: {
    apiBaseUrl: 'https://arc-api.polygon.technology',
  },
});

const core = sdk.getCore();
// native module not available

Native Bridge Only

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

const sdk = new AggLayerSDK({
  mode: [SDK_MODES.NATIVE], // Only Native Bridge
  native: {
    defaultNetwork: 1,
    customRpcUrls: {
      1: process.env.ETHEREUM_RPC_URL,
    },
  },
});

const native = sdk.getNative();
// core module not available

Both Modules

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

const sdk = new AggLayerSDK({
  mode: [SDK_MODES.CORE, SDK_MODES.NATIVE], // Both modules
  core: {
    apiBaseUrl: 'https://arc-api.polygon.technology',
  },
  native: {
    defaultNetwork: 1,
    customRpcUrls: {
      1: process.env.ETHEREUM_RPC_URL,
      747474: process.env.KATANA_RPC_URL,
    },
  },
});

const core = sdk.getCore();
const native = sdk.getNative();

Troubleshooting

Common Issues and Solutions

Node Version Mismatch

Problem: Error: Unsupported Node.js version

Solution:

# Check your Node.js version
node --version

# If below 18.0.0, upgrade Node.js
# Using nvm (recommended)
nvm install 18
nvm use 18

# Or download from nodejs.org

TypeScript Configuration Issues

Problem: Cannot find module '@agglayer/sdk' or type errors

Solution:

// tsconfig.json - ensure these settings
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "target": "ES2020",
    "lib": ["ES2020"]
  }
}

RPC URL Connectivity Problems

Problem: Network request failed or Connection timeout

Solution:

// Test RPC connectivity
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(process.env.ETHEREUM_RPC_URL);
const blockNumber = await provider.getBlockNumber();
console.log(`Connected! Current block: ${blockNumber}`);

Common causes:

  • Invalid or expired API key in RPC URL
  • Rate limiting on free RPC tier
  • Firewall blocking outbound connections
  • Incorrect RPC URL format

Module Not Initialized Error

Problem: Error: Core module not initialized or Native module not initialized

Solution:

// Ensure the module is in the mode array
const sdk = new AggLayerSDK({
  mode: [SDK_MODES.CORE, SDK_MODES.NATIVE], // Include both if you need both
});

// Then you can access both modules
const core = sdk.getCore();
const native = sdk.getNative();

ARC API Connection Issues

Problem: Failed to fetch routes or API timeout

Solution:

// Increase timeout for slow connections
const sdk = new AggLayerSDK({
  mode: [SDK_MODES.CORE],
  core: {
    apiBaseUrl: 'https://arc-api.polygon.technology',
    apiTimeout: 60000, // 60 seconds instead of default 30s
  },
});

Local Testing Issues with AggSandbox

Problem: Cannot connect to local RPC when using AggSandbox

Solution:

# 1. Verify AggSandbox is running
aggsandbox status

# 2. Check ports are accessible
curl http://localhost:8545 -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# 3. Ensure correct RPC URLs in SDK config
const sdk = new AggLayerSDK({
  mode: [SDK_MODES.NATIVE],
  native: {
    customRpcUrls: {
      1: 'http://localhost:8545',     // Not https, not 127.0.0.1
      1101: 'http://localhost:8546',
    },
  },
});
Edit on GitHub

Last updated on

API Reference

Complete TypeScript API documentation for all Agglayer SDK methods, interfaces, and configuration options

Quickstart

Complete your first cross-chain bridge operation in 10 minutes with a direct Base → Katana example

On this page

PrerequisitesSystem RequirementsVerify PrerequisitesInstallationUsing NPMBasic SetupTypeScript Project SetupJavaScript Project SetupEnvironment ConfigurationEnvironment VariablesConfiguration ExamplesLocal ConfigurationTestnet ConfigurationMainnet ConfigurationVerificationTest InstallationModule SelectionMulti-Bridge Routes OnlyNative Bridge OnlyBoth ModulesTroubleshootingCommon Issues and SolutionsNode Version MismatchTypeScript Configuration IssuesRPC URL Connectivity ProblemsModule Not Initialized ErrorARC API Connection IssuesLocal Testing Issues with AggSandbox