Firefly-SDK

Firefly Labs: The ultimate gateway for lightning-fast, cost-effective cross-chain maneuvers.

This SDK simplifies how you interact with the Firefly protocol. To get started, browse our docs. For technical setup and configuration, visit the sdk docs to accelerate your build process.

Installation

You can use the following ways to get the latest version of Firefly SDK:

npm

``bash
npm install @firefly-dao/sdk
`

yarn

`bash
yarn add @firefly-dao/sdk
`

pnpm

`bash
pnpm add @firefly-dao/sdk
`

Quick Start

$3

`typescript
import {
FireflyClient,
MAINNET_FIREFLY_API,
TESTNET_FIREFLY_API,
LogLevel,
} from "@firefly-dao/sdk";

const client = new FireflyClient({
baseApiUrl: MAINNET_FIREFLY_API, // or TESTNET_FIREFLY_API
referrer: "firefly-sdk", // optional, default: 'firefly-sdk'
logLevel: LogLevel.Info, // optional, default: LogLevel.Info
});
`

$3

`typescript
const quote = await client.getQuote({
fromChainId: 8453, // Base
fromTokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
toChainId: 10, // Optimism
toTokenAddress: "0x0000000000000000000000000000000000000000", // USDC
amount: "2000000", // 1 USDC (6 decimals)
recipient: "0x...", // destination address
sender: "0x...", // optional, source address
});

// Quote contains:
// - steps: Transaction steps (approve, deposit)
// - fees: Fee breakdown (gas, service fees)
// - details: Rate, impact, time estimate, currencies info
`

$3

`typescript
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

// Connect wallet
const wallet = createWalletClient({
chain: base,
transport: http(),
account: privateKeyToAccount(0x),
});

// Execute with progress tracking
const result = await client.execute({
quote,
wallet,
onProgress: (info) => {
console.log(Step: ${info.step});
console.log(Status: ${info.status});

if (info.status === "success") {
console.log(Transaction hash: ${info.hash});
}

if (info.status === "failed") {
console.error(Error: ${info.error});
}
},
});

if (result.status === "success") {
console.log("✅ Cross-chain transfer completed!");
} else {
console.error(❌ Transfer failed: ${result.message});
}
`

📖 API Reference

$3

`typescript
new FireflyClient(options: FireflyClientOptions)
`

Parameters:

| Parameter | Type | Required | Default | Description |
| ------------ | ---------- | -------- | --------------- | ------------------------------------------------------------- |
| baseApiUrl | string | Yes | - | API endpoint (MAINNET_FIREFLY_API or TESTNET_FIREFLY_API) |
| referrer | string | No | 'firefly-sdk' | Application identifier for tracking |
| logLevel | LogLevel | No | LogLevel.Info | Logging level (Info or Silent) |

---

$3

`typescript
async getQuote(parameters: GetQuoteParameters): Promise
`

Fetches a quote for cross-chain token transfer.

Parameters:

| Parameter | Type | Required | Description |
| ------------------- | -------- | -------- | ---------------------------------- |
| fromChainId | number | Yes | Source chain ID |
| fromTokenAddress | string | Yes | Source token contract address |
| toChainId | number | Yes | Destination chain ID |
| toTokenAddress | string | Yes | Destination token contract address |
| amount | string | Yes | Amount in smallest unit |
| recipient | string | Yes | Recipient address |
| sender | string | No | Sender address |
| referrer | string | No | Referrer |
| slippageTolerance | string | No | Cross-chain slip pointID |

Returns:

Execute object containing:

- steps: Array of transaction steps
- fees: Fee breakdown (gas, service fees)
- details: Transfer details (currencies, rate, impact, time estimate)

---

$3

`typescript
async execute(options: ExecuteOptions): Promise
`

Executes the cross-chain transfer.

Parameters:

| Parameter | Type | Required | Description |
| ------------ | ------------------------- | -------- | -------------------------- |
| quote | Execute | Yes | Quote from getQuote() |
| wallet | WalletClient | Yes | Viem wallet client |
| onProgress | ExecuteProgressCallback | No | Progress callback function |

Progress Callback:

`typescript
interface ExecuteProgressInfo {
step: "approve" | "deposit";
status: "success" | "failed";
hash?: string;
error?: any;
}
`

Returns:

`typescript
interface ExecuteResponse {
status: "idle" | "failed" | "success";
message: string;
}
`

Complete Example

`typescript
import {
FireflyClient,
MAINNET_FIREFLY_API,
LogLevel,
} from "@firefly-dao/sdk";
import { createWalletClient } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

async function main() {
// 1. Initialize client
const client = new FireflyClient({
baseApiUrl: MAINNET_FIREFLY_API,
referrer: "my-dapp",
logLevel: LogLevel.Info,
});

// 2. Setup wallet
const wallet = createWalletClient({
chain: base,
transport: http(),
account: privateKeyToAccount(0x),
});

try {
// 3. Get quote
console.log("Getting quote...");
const quote = await client.getQuote({
fromChainId: 8453, // Base Mainnet
fromTokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
toChainId: 10, // Optimism Mainnet
toTokenAddress: "0x0000000000000000000000000000000000000000", // Optimism USDC
amount: "2000000", // 2 USDC (6 decimals)
recipient: "0x...", // destination address
sender: "0x...", // optional, source address
});

console.log("Quote result:", quote);

// 4. Execute transfer
console.log("Executing transfer...");
const result = await client.execute({
quote,
wallet,
onProgress: (info) => {
if (info.step === "approve") {
console.log("Approval:", info.status);
} else if (info.step === "deposit") {
console.log("Deposit:", info.status);
}

if (info.hash) {
console.log("Transaction:", info.hash);
}
},
});

if (result.status === "success") {
console.log("Transfer completed successfully!");
} else {
console.error("Transfer failed:", result.message);
}
} catch (error) {
console.error("Error:", error);
}
}

main();
``