@defuse-protocol/intents-sdk

A comprehensive SDK for Near Intents protocol. This SDK provides tools for intent execution, deposits, withdrawals, and interacting with various bridge implementations across multiple blockchains.

Table of Contents

• Installation
• Features
• Quick Start
• Core Functionalities
  • Core Concepts
  • Intent Execution
  • Deposits
  • Withdrawals
    • Routes and Bridges
    • Route Types
    • Fee Estimation
• Advanced Usage
  • Custom RPC URLs
  • Feature Flags
  • Other Intent Signers
  • Intent Payload Builder
  • Intent Publishing Hooks
  • Batch Withdrawals
  • Waiting for Batch Completion
  • Intent Management
  • Nonce Invalidation
  • Configure Withdrawal Routes
  • Asset Information Parsing
  • Waiting for Completion
  • Error Handling
  • Atomic Multi-Intent Publishing
• Supported Networks
• Development

Installation

npm install @defuse-protocol/intents-sdk --save-exact

Features

| Feature | Status | Description | |------------------|:------:|------------------------------------------------------------------------| | Intent Execution | ✅ | Sign, submit, and track intent execution on Near Intents | | Deposits | ❌ | Deposit funds to Near Intents (use bridge interfaces directly) | | Withdrawals | ✅ | Complete withdrawal functionality from Near Intents to external chains |

Quick Start

Basic Setup

First, initialize the SDK with your referral code and intent signer:

import {IntentsSDK, createIntentSignerNearKeyPair} from '@defuse-protocol/intents-sdk';
import {KeyPair} from 'near-api-js';

// Initialize the SDK
const sdk = new IntentsSDK({
    referral: 'your-referral-code', // Only referral is required
    intentSigner: createIntentSignerNearKeyPair({
        signer: KeyPair.fromString('your-private-key'),
        accountId: 'your-account.near'
    })
});

Most Common Use Case: Withdrawals

For most users, the primary use case is withdrawing funds from Near Intents to external chains. Use the high-level processWithdrawal method:

// Complete end-to-end withdrawal (recommended)
const result = await sdk.processWithdrawal({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near', // USDT token on NEAR
        amount: 1000000n, // 1 USDT (in smallest units - 6 decimals)
        destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3', // Ethereum address
        feeInclusive: false, // Amount excludes withdrawal fees
    }
});

console.log('Intent hash:', result.intentHash);
console.log('Destination transaction:', result.destinationTx);

Advanced Use Case: Custom Intents

For advanced users who need custom intent logic beyond withdrawals, use the lower-level signAndSendIntent method:

// Custom intent execution (advanced)
const result = await sdk.signAndSendIntent({
    intents: [
        {
            intent: "transfer", // Custom intent type
            receiver_id: "recipient.near",
            tokens: {"usdt.tether-token.near": "1000000"}, // 1 USDT
        },
    ],
});

console.log('Intent hash:', result.intentHash);

💡 Tip: Use processWithdrawal for withdrawals and signAndSendIntent for custom intent logic. The withdrawal method handles fee estimation, validation, and completion tracking automatically.

Core Functionalities

Core Concepts

Intent

TBD

Intent Signers

Intent signers are required to authenticate and sign both regular and withdrawal intents. The SDK supports multiple signing methods:

| Singing Standard | Methods | Description | |------------------|:------------------------------------------------------------------:|----------------------------------------------------------| | nep413 | createIntentSignerNEP413()createIntentSignerNearKeyPair() | Almost all NEAR wallets support this standard | | erc191 | createIntentSignerViem() | Only Viem library supported, Ethers.js signer is coming | | raw_ed25519 | ❌ | Available on the protocol level, but not included to SDK | | webauthn | ❌ | Available on the protocol level, but not included to SDK | | ton_connect | ❌ | Available on the protocol level, but not included to SDK |

You must set an intent signer before processing withdrawals:

// Example: Set up a NEAR KeyPair signer
const signer = createIntentSignerNearKeyPair({
    signer: KeyPair.fromString('your-private-key'),
    accountId: 'your-account.near'
});
sdk.setIntentSigner(signer);

See the Intent Signers section below for detailed implementation examples.

Asset Identifiers

The SDK uses standardized asset identifiers in the format:

• nep141:contract.near - NEP-141 tokens
• nep245:contract.near:tokenId - NEP-245 multi-tokens

Asset Identifier uniquely determines the corresponding withdrawal route and destination chain.

Examples:

• nep141:usdt.tether-token.near - USDT on NEAR
• nep141:wrap.near - Wrapped NEAR (native NEAR)
• nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L - Polygon USDC through Hot
• nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near - Base USDC through PoA
• nep141:sol.omdep.near - SOL bridged through Omni Bridge

Intent Execution

The primary functionality of the SDK - execute custom intents on Near Intents:

• Sign Intents: Create and sign intent payloads with various signer types
• Submit Intents: Publish intents to the Near Intents relayer network
• Track Status: Monitor intent settlement and execution status
• Batch Intents: Execute multiple intents in a single transaction
• Custom Logic: Support for any intent type supported by the protocol

// Generic intent execution
const {intentHash} = await sdk.signAndSendIntent({
    intents: [/* array of intent primitives */],
    onBeforePublishIntent: async (data) => {
        console.log('About to publish intent:', data.intentHash);
    }
});

// Monitor settlement
const intentTx = await sdk.waitForIntentSettlement({intentHash});

Deposits

Deposit funds into Near Intents (Coming Soon).

Note: Deposit functionality is not yet implemented in this SDK. Currently, use bridge interfaces directly for deposit operations.

Withdrawals

Complete withdrawal functionality from Near Intents to external chains:

• Cross-Chain Transfers: Withdraw to 20+ supported blockchains
• Multi-Bridge Support: Hot Bridge, PoA Bridge, Omni Bridge
• Batch Processing: Process multiple withdrawals at a time
• Fee Management: Automatic fee estimation with quote support
• Validation: Built-in validation for withdrawal constraints
• Status Tracking: End-to-end monitoring from intent to destination

// Complete withdrawal process
const result = await sdk.processWithdrawal({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
        feeInclusive: false
    }
});

Routes and Bridges

The SDK uses two key concepts to organize withdrawal operations:

Routes

Routes define the path a withdrawal takes - the specific mechanism and destination for transferring assets. Each route represents a different withdrawal flow:

import {RouteEnum} from '@defuse-protocol/intents-sdk';

console.log(RouteEnum.HotBridge);        // "hot_bridge" - Cross-chain via HOT protocol
console.log(RouteEnum.PoaBridge);        // "poa_bridge" - Cross-chain via PoA bridge
console.log(RouteEnum.OmniBridge);       // "omni_bridge" - Cross-chain via Omni bridge
console.log(RouteEnum.NearWithdrawal);   // "near_withdrawal" - Direct to NEAR blockchain
console.log(RouteEnum.VirtualChain);     // "virtual_chain" - To Aurora Engine chains
console.log(RouteEnum.InternalTransfer); // "internal_transfer" - Between protocol users

Bridge Names

Bridge names identify the underlying bridge infrastructure that handles the cross-chain transfer. This determines which external protocol processes the withdrawal:

import {BridgeNameEnum} from '@defuse-protocol/intents-sdk';

console.log(BridgeNameEnum.Hot);  // "hot" - HOT Labs bridge infrastructure
console.log(BridgeNameEnum.Poa);  // "poa" - Proof-of-Authority bridge by Defuse Labs  
console.log(BridgeNameEnum.Omni);  // "omni" - Omni bridge by NEAR 
console.log(BridgeNameEnum.None); // null - No external bridge (NEAR-native or internal)

Key Difference:

• Route = "How and where" the withdrawal goes (the path)
• Bridge Name = "Who operates" the underlying infrastructure (the bridge provider)

For example, both hot_bridge and poa_bridge routes perform cross-chain transfers, but use different bridge infrastructures (hot vs poa) with different fee structures and supported networks.

Route Types

The SDK automatically detects and supports multiple route types based on asset identifiers:

Hot Bridge Route

• Purpose: Cross-chain transfers via HOT Labs infrastructure
• Supported Assets: Multi-tokens (NEP-245) from Hot protocol (contract v2_1.omni.hot.tg)
• Use Case: Cross-chain transfers for assets bridged through Hot protocol
• Route Type: hot_bridge

PoA Bridge Route

• Purpose: Proof-of-Authority bridge transfers operated by Defuse Labs
• Supported Assets: Fungible tokens (NEP-141) ending with .omft.near
• Use Case: Cross-chain transfers for assets bridged through PoA protocol
• Route Type: poa_bridge

Omni Bridge Route

• Purpose: multi-chain asset bridge developed by Near
• Supported Assets: Fungible tokens (NEP-141) supported by omni bridge relayer.
• Use Case: multi-chain transfers for supported list of chains
• Route Type: omni_bridge

Internal Transfer Route

• Purpose: Transfer between Near Intents users within the protocol
• Supported Assets: All NEP-141 and NEP-245 tokens
• Use Case: User A having funds in the protocol wants to transfer to User B
• Route Type: internal_transfer

Near Withdrawal Route

• Purpose: Transfers within the NEAR blockchain
• Supported Assets: NEP-141 tokens on NEAR, including native NEAR (wrap.near)
• Use Case: Same-chain transfers on NEAR
• Route Type: near_withdrawal

Virtual Chain Route

• Purpose: Transfers to Aurora Engine-powered chains (aka Virtual chains)
• Supported Assets: NEP-141 tokens with Aurora Engine integration
• Use Case: Near Intents to Aurora ecosystem transfers
• Route Type: virtual_chain
• Note: Requires explicit routeConfig with auroraEngineContractId

Fee Estimation

The SDK now supports both single and batch fee estimation:

// Single withdrawal fee estimation
const feeEstimation = await sdk.estimateWithdrawalFee({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
        feeInclusive: false
    }
});

console.log('Fee amount:', feeEstimation.amount);

// Batch fee estimation
const batchFees = await sdk.estimateWithdrawalFee({
    withdrawalParams: [
        {
            assetId: 'nep141:usdt.tether-token.near',
            amount: 1000000n,
            destinationAddress: '0x742d35Cc...',
            feeInclusive: false
        },
        {
            assetId: 'nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L',
            amount: 500000n,
            destinationAddress: '0x742d35Cc...',
            feeInclusive: false
        }
    ]
});

console.log('Batch fees:', batchFees); // Array of FeeEstimation objects

Note: estimateWithdrawalFee also runs validateWithdrawal internally. If the withdrawal parameters are invalid (e.g. invalid destination address, amount below minimum, insufficient UTXOs), the bridge's validateWithdrawal will throw and the error will propagate from estimateWithdrawalFee.

Advanced Usage

Custom RPC URLs

Set NEAR and EVM chains RPC URLs in the constructor:

import {Chains} from '@defuse-protocol/intents-sdk'

const sdk = new IntentsSDK({
    ...,
    rpc: {
        [Chains.Near]: ['https://rpc.mainnet.near.org'],
        [Chains.Polygon]: ['https://polygon-rpc.com'],
        [Chains.BNB]: ['https://bsc-dataseed.binance.org'],
    }
});

Feature Flags

Configure optional SDK features through the features configuration:

Migrated PoA Token Routing

Will route migrated PoA tokens (ending with *.omft.near) through Omni Bridge instead of the legacy PoA Bridge, unless explicitly set to route them through PoA bridge with routeConfig. Enable this when working with POA tokens that have been migrated to the Omni infrastructure:

const sdk = new IntentsSDK({
    referral: 'your-referral-code',
    features: {
        routeMigratedPoaTokensThroughOmniBridge: true
    }
});

// With this flag enabled, tokens like 'nep141:sol-c58e6539c2f2e097c251f8edf11f9c03e581f8d4.omft.near' will route through Omni Bridge
const result = await sdk.processWithdrawal({
    withdrawalParams: {
        assetId: 'nep141:sol-c58e6539c2f2e097c251f8edf11f9c03e581f8d4.omft.near', // Migrated PoA token
        amount: 1000000n,
        destinationAddress: '39hqXivfCPUSqmXAaX3eo4JcA5bGFXhhs26dmg585DGb',
        feeInclusive: false
    }
});

When to enable:

• Working with PoA tokens that have been migrated to Omni Bridge
• Explicitly want to route *.omft.near tokens through the Omni Bridge
• Default behavior (when disabled) routes these tokens through the PoA Bridge

Allowlisted Tokens:

Not all PoA tokens can be routed through Omni Bridge. The SDK exports POA_TOKENS_ROUTABLE_THROUGH_OMNI_BRIDGE constant containing the tokens that support this routing:

import { POA_TOKENS_ROUTABLE_THROUGH_OMNI_BRIDGE } from '@defuse-protocol/intents-sdk';

console.log(POA_TOKENS_ROUTABLE_THROUGH_OMNI_BRIDGE);
// { 'sol-...omft.near': ChainKind.Sol, ... }

The keys are token contract IDs and values are their ChainKind. Only tokens in this map will be routed through Omni Bridge when the feature flag is enabled. Other *.omft.near tokens will continue using the PoA Bridge.

Other Intent Signers

The SDK supports multiple intent signing methods using factory functions:

NEAR KeyPair Signer

import {createIntentSignerNearKeyPair, IntentsSDK} from '@defuse-protocol/intents-sdk';
import {KeyPair} from 'near-api-js';

const keyPair = KeyPair.fromString('your-private-key');
const signer = createIntentSignerNearKeyPair({
    signer: keyPair,
    accountId: 'your-account.near'
});

NEP-413 Signer

import {createIntentSignerNEP413} from '@defuse-protocol/intents-sdk';

const signer = createIntentSignerNEP413({
    signMessage: async (nep413Payload, nep413Hash) => {
        // Implement your custom signing logic here
        return {
            publicKey: 'ed25519:YourPublicKey',
            signature: 'base64-encoded-signature'
        };
    },
    accountId: 'your-account.near'
});

EVM/Viem Signer

import {createIntentSignerViem} from '@defuse-protocol/intents-sdk';
import {privateKeyToAccount} from 'viem/accounts';

const account = privateKeyToAccount('0x...');
const signer = createIntentSignerViem({ signer: account });

// Set the signer at runtime
sdk.setIntentSigner(signer);

Intent Payload Builder

For API builders who need to generate intent payloads based on user metadata (e.g., generating payloads server-side for users to sign with MetaMask), the SDK provides a fluent IntentPayloadBuilder:

// Build an intent payload for your users
const payload = await sdk.intentBuilder()
    .setSigner('0x742d35cc6634c0532925a3b8d84b2021f90a51a3') // User's EVM address
    .setDeadline(new Date(Date.now() + 5 * 60 * 1000)) // 5 minutes
    .addIntent({
        intent: "transfer",
        tokens: { "token.near": "100" },
        receiver_id: "receiver.near",
    })
    .build();

Versioned Nonce Builder

By default, the nonce is generated during the intent construction process, but it is possible to generate and pass the nonce within the builder independently. All of the nonces have specific requirements for the structure reflecting their validity.

import {VersionedNonceBuilder} from '@defuse-protocol/intents-sdk';

// Fetch current salt from the verifier contract
const salt_hex = await nearRPC.viewFunction({
  contractId: "intents.near",
  methodName: "current_salt",
});

// Example: 5-minute deadline, but actual deadline should not be greater than intent's deadline
const deadline = new Date(Date.now() + 5 * 60 * 1000)

// Create ready to use versioned nonce from salt and deadline
const versionedNonce = VersionedNonceBuilder.encodeNonce(
  Uint8Array.from(Buffer.from(salt_hex, "hex")),
  deadline
);

// Create intent builder with specified nonce
const builder = await sdk.intentBuilder().setNonce(versionedNonce);

Intent Publishing Hooks

Use the onBeforePublishIntent hook to intercept and process intent data before it's published to the relayer. This is useful for persistence, logging, analytics, or custom processing:

import {type OnBeforePublishIntentHook} from '@defuse-protocol/intents-sdk';

// Define your hook function
const onBeforePublishIntent: OnBeforePublishIntentHook = async (intentData) => {
    // Save to database for tracking
    await saveIntentToDatabase({
        hash: intentData.intentHash,
        payload: intentData.intentPayload,
        timestamp: new Date(),
    });

    // Send analytics
    analytics.track('intent_about_to_publish', {
        intentHash: intentData.intentHash,
        intentType: intentData.intentPayload.intents[0]?.intent,
    });
};

// Use the hook with the functional API
const result = await sdk.processWithdrawal({
    withdrawalParams: { /* ... */},
    intent: {
        onBeforePublishIntent, // Add the hook here
    }
});

// Or with granular control
const {intentHash} = await sdk.signAndSendWithdrawalIntent({
    withdrawalParams: { /* ... */},
    feeEstimation: fee,
    intent: {
        onBeforePublishIntent, // Add the hook here
    }
});

// Or with generic intent publishing
const {intentHash} = await sdk.signAndSendIntent({
    intents: [/* ... */],
    onBeforePublishIntent, // Add the hook here
});

Hook Parameters:

• intentHash - The computed hash of the intent payload
• intentPayload - The unsigned intent payload
• multiPayload - The signed multi-payload containing signature and metadata
• relayParams - Additional parameters passed to the relayer (quote hashes)

Important Notes:

• The hook is called synchronously before publishing the intent
• If the hook throws an error, the withdrawal will fail
• The hook can be async and return a Promise

Batch Withdrawals

Process multiple withdrawals in a single intent:

const withdrawalParams = [
    {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc...',
        feeInclusive: false
    },
    {
        assetId: 'nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L',
        amount: 100000n,
        destinationAddress: '0x742d35Cc...',
        feeInclusive: false
    }
]

// Method 1: Complete end-to-end batch processing
const batchResult = await sdk.processWithdrawal({
    withdrawalParams,
    // feeEstimation is optional - will be estimated automatically if not provided
});

console.log('Batch intent hash:', batchResult.intentHash);
console.log('Destination transactions:', batchResult.destinationTx); // Array of results

// Method 2: Step-by-step batch processing for granular control
const feeEstimation = await sdk.estimateWithdrawalFee({
    withdrawalParams
});

const {intentHash} = await sdk.signAndSendWithdrawalIntent({
    withdrawalParams,
    feeEstimation
});

const intentTx = await sdk.waitForIntentSettlement({intentHash});

// See "Waiting for Batch Completion" below for completion options

Waiting for Batch Completion

After the intent settles on NEAR, you need to wait for withdrawals to complete on destination chains. Two approaches are available:

Option A: Wait for All (waitForWithdrawalCompletion)

Waits for all withdrawals to complete before returning. Simple, but blocks on the slowest withdrawal.

Note: Waits until completion or chain-specific p99 timeout (throws PollTimeoutError). Use AbortSignal.timeout() to set a shorter timeout.

const destinationTxs = await sdk.waitForWithdrawalCompletion({
    withdrawalParams,
    intentTx,
    signal: AbortSignal.timeout(10 * 60 * 1000), // 10 minute timeout
});

console.log('All destination transactions:', destinationTxs);

Option B: Independent Promises (createWithdrawalCompletionPromises)

For scenarios where fast withdrawals (Solana ~2s) shouldn't wait for slow ones (Bitcoin ~1hr), use createWithdrawalCompletionPromises to get promises that resolve independently:

// Get array of promises - one per withdrawal
const promises = sdk.createWithdrawalCompletionPromises({
    withdrawalParams,
    intentTx
});

// Fire and forget - handle each independently
promises[0].then(tx => saveUsdc(tx)).catch(err => logError(0, err));
promises[1].then(tx => saveBtc(tx)).catch(err => logError(1, err));

// Or await a specific withdrawal (fast chain first)
const usdcTx = await promises[0];
await notifyUser('USDC received', usdcTx.hash);

// Or process as they complete with backpressure
const pending = new Map(promises.map((p, i) => [i, p]));
while (pending.size > 0) {
    const { index, tx } = await Promise.race(
        [...pending.entries()].map(async ([i, p]) => ({ index: i, tx: await p }))
    );
    pending.delete(index);
    await saveSuccess(index, tx);  // Backpressure maintained
}

// Or wait for all with independent error handling
const results = await Promise.allSettled(promises);
for (const [i, result] of results.entries()) {
    if (result.status === 'fulfilled') {
        await saveSuccess(i, result.value);
    } else {
        await saveFailure(i, result.reason);
    }
}

With timeout control:

const promises = sdk.createWithdrawalCompletionPromises({
    withdrawalParams,
    intentTx,
    signal: AbortSignal.timeout(30_000)  // 30 second timeout
});

Key benefits:

• Fast withdrawals (Solana ~2s) aren't blocked by slow ones (Bitcoin ~1hr)
• One failure doesn't affect other withdrawals
• Recovery-friendly: recreate promises from saved { withdrawalParams, intentTx }
• Index correspondence: promises[i] corresponds to withdrawalParams[i]

Note: Both methods wait until completion or chain-specific p99 timeout (throws PollTimeoutError). Use AbortSignal.timeout() for a shorter timeout.

Intent Management

The SDK provides direct access to intent operations for advanced use cases:

// Generic intent signing and publishing
const {intentHash} = await sdk.signAndSendIntent({
    intents: [/* array of intent primitives */],
    signer: customIntentSigner, // optional - uses SDK default if not provided
    onBeforePublishIntent: async (data) => {
        // Custom logic before publishing
        console.log('About to publish intent:', data.intentHash);
    }
});

// Wait for intent settlement
const intentTx = await sdk.waitForIntentSettlement({
    intentHash
});

// or manual status check

// Check intent status at any time
const status = await sdk.getIntentStatus({
    intentHash: intentHash
});

console.log('Intent status:', status.status); // "PENDING" | "TX_BROADCASTED" | "SETTLED" | "NOT_FOUND_OR_NOT_VALID"

if (status.status === 'SETTLED') {
    console.log('Settlement transaction:', status.txHash);
}

Intent Status Values:

• PENDING - Intent published but not yet processed
• TX_BROADCASTED - Intent being processed, transaction broadcasted
• SETTLED - Intent successfully completed
• NOT_FOUND_OR_NOT_VALID - Intent not found or invalid, it isn't executed onchain

Nonce Invalidation

Invalidate nonces to prevent execution of previously created intent payloads. Primarily used by solvers to revoke quotes due to price volatility, liquidity changes, or risk management.

await sdk.invalidateNonces({
    nonces: ['VigoxLwmUGf35MGLVBG9Fh5cCtJw3D68pSKFcqGCkHU='],
    signer: customIntentSigner, // optional - uses SDK default if not provided
});

Configure Withdrawal Routes

Recommended: Use factory functions to create route configurations. The SDK provides factory functions for type-safe and convenient route configuration creation:

import {
    createVirtualChainRoute,
    createNearWithdrawalRoute,
    createInternalTransferRoute
} from '@defuse-protocol/intents-sdk';

// Create virtual chain route configuration (recommended)
const virtualChainRoute = createVirtualChainRoute(
    '0x4e45415f.c.aurora', // Aurora Engine contract ID
    null // Proxy token contract ID (optional)
);

// Create near withdrawal route with custom message
const nearWithdrawalRoute = createNearWithdrawalRoute(
    'Custom withdrawal message' // Optional message
);

// Create internal transfer route
const internalTransferRoute = createInternalTransferRoute();

// Use the factory-created route configuration in withdrawal
const result = await sdk.processWithdrawal({
    withdrawalParams: {
        assetId: 'nep141:a35923162c49cf95e6bf26623385eb431ad920d3.factory.bridge.near',
        amount: BigInt('1000000'),
        destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
        feeInclusive: false,
        routeConfig: virtualChainRoute // Recommended: Use factory function
    }
});

Asset Information Parsing

Get detailed information about supported assets:

try {
    const assetInfo = sdk.parseAssetId('nep141:usdt.tether-token.near');
    console.log('Bridge name:', assetInfo.bridgeName);
    console.log('Blockchain:', assetInfo.blockchain);
    console.log('Contract ID:', assetInfo.contractId);
    console.log('Standard:', assetInfo.standard);
} catch (error) {
    console.log('Asset not supported');
}

Waiting for Completion

Monitor withdrawal completion:

// Method 1: Using the orchestrated approach (automatic monitoring)
const result = await sdk.processWithdrawal({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc...',
        feeInclusive: false
    }
});

console.log('Intent settled:', result.intentTx.hash);
console.log('Withdrawal completed:', result.destinationTx);

// Method 2: Step-by-step monitoring for granular control
const feeEstimation = await sdk.estimateWithdrawalFee({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc...',
        feeInclusive: false
    }
});

const {intentHash} = await sdk.signAndSendWithdrawalIntent({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc...',
        feeInclusive: false
    },
    feeEstimation
});

// Monitor intent settlement
const intentTx = await sdk.waitForIntentSettlement({intentHash});
console.log('Intent settled:', intentTx.hash);

// Wait for withdrawal completion on destination chain
// Note: Has chain-specific p99 timeout - use signal for a shorter timeout
const completionResult = await sdk.waitForWithdrawalCompletion({
    withdrawalParams: {
        assetId: 'nep141:usdt.tether-token.near',
        amount: 1000000n,
        destinationAddress: '0x742d35Cc...',
        feeInclusive: false
    },
    intentTx,
    signal: AbortSignal.timeout(10 * 60 * 1000), // 10 minute timeout
});

if ('hash' in completionResult) {
    console.log('Withdrawal completed with hash:', completionResult.hash);
} else {
    console.log('Withdrawal completion not trackable for this bridge');
}

Error Handling

import {FeeExceedsAmountError, MinWithdrawalAmountError} from '@defuse-protocol/intents-sdk';

try {
    const result = await sdk.processWithdrawal({
        withdrawalParams: {
            assetId: 'nep141:usdt.tether-token.near',
            amount: BigInt('100'), // Very small amount
            destinationAddress: '0x742d35Cc...',
            feeInclusive: true // Fee must be less than amount
        }
    });
} catch (error) {
    if (error instanceof FeeExceedsAmountError) {
        console.log('Fee exceeds withdrawal amount');
        console.log('Required fee:', error.feeEstimation.amount);
        console.log('Withdrawal amount:', error.amount);
    } else if (error instanceof MinWithdrawalAmountError) {
        console.log('Amount below minimum withdrawal limit');
        console.log('Minimum required:', error.minAmount);
        console.log('Requested amount:', error.requestedAmount);
        console.log('Asset:', error.assetId);
    }
}

// Error handling with granular control
try {
    const feeEstimation = await sdk.estimateWithdrawalFee({
        withdrawalParams: {
            assetId: 'nep141:usdt.tether-token.near',
            amount: 100n,
            destinationAddress: '0x742d35Cc...',
            feeInclusive: true
        }
    });

    // Continue with other operations...
} catch (error) {
    // Handle specific errors at each step
    console.error('Fee estimation failed:', error);
}

PoA Bridge Minimum Withdrawal Amount Validation

PoA bridge has minimum withdrawal amount requirements that vary per token and blockchain. The SDK automatically validates this for all withdrawals.

// Validation happens automatically during withdrawal processing:
try {
    const result = await sdk.processWithdrawal({
        withdrawalParams: {
            assetId: 'nep141:zec.omft.near', // Zcash token
            amount: BigInt('50000000'), // 0.5 ZEC (in smallest units)
            destinationAddress: 'your-zcash-address',
            feeInclusive: false
        }
    });
} catch (error) {
    if (error instanceof MinWithdrawalAmountError) {
        console.log(`Minimum withdrawal for ${error.assetId}: ${error.minAmount}`);
        console.log(`Requested amount: ${error.requestedAmount}`);
        // For Zcash: minimum is typically 1.0 ZEC (100000000 in smallest units)
        // Plus 0.2 ZEC fee, so user needs at least 1.2 ZEC to withdraw 1.0 ZEC
    }
}

Note: Other routes (Near Withdrawal, Virtual Chain, Internal Transfer) don't have minimum withdrawal restrictions, so validation passes through for those routes.

Hot Bridge Stellar Trustline Validation

Hot Bridge validates that destination addresses have the required trustlines when withdrawing to Stellar blockchain. This prevents failed transactions due to missing trustlines.

import {TrustlineNotFoundError} from '@defuse-protocol/intents-sdk';

// Validation happens automatically during withdrawal processing:
try {
    const result = await sdk.processWithdrawal({
        withdrawalParams: {
            assetId: 'nep245:v2_1.omni.hot.tg:stellar_1_USD_GBDMM6LG7YX7YGF6JFAEWX3KFUSBXGAEPZ2IHDLWH:1100', // Stellar USD token
            amount: BigInt('1000000'), // 1 USD (in smallest units)
            destinationAddress: 'GCKFBEIYTKP6RYVDYGMVVMJ6J6XKCRZL74JPWTFGD2NQNMPBQC2LGTVZ', // Stellar address
            feeInclusive: false
        }
    });
} catch (error) {
    if (error instanceof TrustlineNotFoundError) {
        console.log(`Trustline not found for token: ${error.assetId}`);
        console.log(`Destination address: ${error.destinationAddress}`);
        console.log('The destination address must have a trustline for this token before withdrawal');
        // User needs to create a trustline for the token on Stellar before withdrawing
    }
}

What is a trustline? On Stellar, accounts must explicitly create "trustlines" to hold non-native assets. Before receiving any token (except XLM), the destination address must:

1. Create a trustline for that specific token
2. Have sufficient XLM balance to maintain the trustline

Why this validation matters:

• Prevents failed withdrawals due to missing trustlines
• Saves gas fees and reduces user frustration
• Provides clear error messages for troubleshooting

Note: This validation only applies to Stellar destinations via Hot Bridge. Other blockchains and routes don't require trustline validation.

Omni Bridge Withdrawal Validation

SDK verifies that the token exists on the destination chain.

import { TokenNotFoundInDestinationChainError } from '@defuse-protocol/intents-sdk';

try {
    const result = await sdk.processWithdrawal({
        withdrawalParams: {
            assetId: 'nep141:aaaaaa20d9e0e2461697782ef11675f668207961.factory.bridge.near', // Aurora token
            amount: 70000000000000000000n, // 70 Aurora (in smallest units)
            destinationAddress: '0x741b0b0F27c4b4047ecFCcDf4690F749C6Cfd66c',
            feeInclusive: false
        }
    });
} catch (error) {
    if (error instanceof TokenNotFoundInDestinationChainError) {
        console.log(`Token ${error.token} was not found on ${error.destinationChain}.`);
    }
}

Atomic Multi-Intent Publishing

Include pre-signed intents (from other users or prior operations) to be published atomically with your new intent. Useful for multi-user coordination and batch operations.

import type { MultiPayload } from '@defuse-protocol/intents-sdk';

// Include pre-signed intents before/after your new intent
await sdk.signAndSendIntent({
    intents: [{ intent: "transfer", receiver_id: "alice.near", tokens: {...} }],
    signedIntents: {
        before: [preSigned1],  // Execute before new intent
        after: [preSigned2]    // Execute after new intent
    }
});

// Also works with withdrawals
await sdk.processWithdrawal({
    withdrawalParams: {...},
    intent: {
        signedIntents: {
            before: [preSigned1],
            after: [preSigned2]
        }
    }
});

Key Points:

• All intents execute atomically in order: before → new intent → after
• Returned intentHash is for your newly created intent, not the included ones

Supported Networks

For a list of supported chains, see the Chain Support page in the Near Intents documentation.

Development

Prerequisites

• Node.js (v20 or later)
• pnpm for package management

Setup

# Install dependencies (from the monorepo root)
pnpm install

Build

# Build the package
pnpm run build

# Build in watch mode
pnpm run dev

Test

# Run tests
pnpm run test

# Run tests in watch mode  
pnpm run test:watch

Lint and Format

# Check code style
pnpm run lint

# Format code
pnpm run format

Version History

See CHANGELOG.md for detailed version history and migration guides.

Contributing

This package is part of Near Intents SDK monorepo. Please refer to the main repository's contributing guidelines.

License

MIT License © 2025 NEAR Foundation