# @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.

Latest version **0.90.0** (published 2026-10-09) · 0 weekly downloads

## Install

```sh
npm install @defuse-protocol/intents-sdk
pnpm add @defuse-protocol/intents-sdk
yarn add @defuse-protocol/intents-sdk
bun add @defuse-protocol/intents-sdk
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.90.0 |
| Published | 2026-10-09 |
| First published | 2025-08-06 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 15 |
| Unpacked size | 556.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 17 |
| Maintainers | cawabunga_aurora |

## Links

- npm: https://www.npmjs.com/package/@defuse-protocol/intents-sdk
- Repository: https://github.com/defuse-protocol/sdk-monorepo
- Homepage: https://github.com/defuse-protocol/sdk-monorepo/tree/main/packages/intents-sdk#readme
- Issues: https://github.com/defuse-protocol/sdk-monorepo/issues
- npm.io page: https://npm.io/package/@defuse-protocol/intents-sdk

## Dependencies (15)

- [viem](https://npm.io/package/viem.md) ^2.0.0
- [borsher](https://npm.io/package/borsher.md) ^4.0.0
- [valibot](https://npm.io/package/valibot.md) ^1.0.0
- [lru-cache](https://npm.io/package/lru-cache.md) ^11
- [@scure/base](https://npm.io/package/@scure/base.md) ^1.0.0
- [near-api-js](https://npm.io/package/near-api-js.md) ^4.0.0 || ^5.0.0
- [@noble/hashes](https://npm.io/package/@noble/hashes.md) ^1.7.1
- [@isaacs/ttlcache](https://npm.io/package/@isaacs/ttlcache.md) ^1.0.0
- [@lifeomic/attempt](https://npm.io/package/@lifeomic/attempt.md) ^3.0.0
- [@omni-bridge/core](https://npm.io/package/@omni-bridge/core.md) 0.20.0
- [@omni-bridge/near](https://npm.io/package/@omni-bridge/near.md) 0.20.0
- [@hot-labs/omni-sdk](https://npm.io/package/@hot-labs/omni-sdk.md) 2.25.5
- [ripple-address-codec](https://npm.io/package/ripple-address-codec.md) ^5.0.0
- [@defuse-protocol/contract-types](https://npm.io/package/@defuse-protocol/contract-types.md) 0.6.4
- [@defuse-protocol/internal-utils](https://npm.io/package/@defuse-protocol/internal-utils.md) 0.42.0

## Recent versions

- 0.90.0 (latest) — 2026-10-09
- 0.89.0 — 2026-10-05
- 0.88.1 — 2026-09-28
- 0.88.0 — 2026-09-21
- 0.87.0 — 2026-09-18
- 0.86.0 — 2026-09-17
- 0.85.1 — 2026-09-15
- 0.85.0 — 2026-09-10
- 0.84.0 — 2026-09-08
- 0.83.0 — 2026-09-01
- 0.82.0 — 2026-08-27
- 0.81.0 — 2026-08-24
- 0.80.0 — 2026-08-14
- 0.79.0 — 2026-08-13
- 0.78.1 — 2026-08-06
- … 124 more at https://npm.io/package/@defuse-protocol/intents-sdk/versions

## README

# @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](#installation)
- [Features](#features)
- [Quick Start](#quick-start)
- [Core Functionalities](#core-functionalities)
  - [Core Concepts](#core-concepts)
  - [Intent Execution](#intent-execution)
  - [Deposits](#deposits)
  - [Withdrawals](#withdrawals)
    - [Routes and Bridges](#routes-and-bridges)
    - [Route Types](#route-types)
    - [Fee Estimation](#fee-estimation)
    - [Prefunded Withdrawal Fees](#prefunded-withdrawal-fees)
- [Advanced Usage](#advanced-usage)
  - [Custom RPC URLs](#custom-rpc-urls)
  - [Feature Flags](#feature-flags)
  - [Other Intent Signers](#other-intent-signers)
  - [Intent Payload Builder](#intent-payload-builder)
  - [Intent Publishing Hooks](#intent-publishing-hooks)
  - [Batch Withdrawals](#batch-withdrawals)
  - [Waiting for Batch Completion](#waiting-for-batch-completion)
  - [Intent Management](#intent-management)
  - [Nonce Invalidation](#nonce-invalidation)
  - [Configure Withdrawal Routes](#configure-withdrawal-routes)
  - [Asset Information Parsing](#asset-information-parsing)
  - [Waiting for Completion](#waiting-for-completion)
  - [Error Handling](#error-handling)
  - [Atomic Multi-Intent Publishing](#atomic-multi-intent-publishing)
- [Supported Networks](#supported-networks)
- [Development](#development)

## Installation

```bash
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:

```typescript
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:

```typescript
// 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:

```typescript
// 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()`<br/>`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:

```typescript
// 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](#intent-signers-1) 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:eth.bridge.near` - ETH 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

```typescript
// 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

```typescript
// 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:

```typescript
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:

```typescript
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`
- **Note**: Some tokens originally issued via the PoA Bridge (`.omft.near`) have since migrated to the Omni Bridge.
  The SDK tracks these in `POA_TOKENS_MIGRATED_TO_OMNI_BRIDGE` and automatically routes them through Omni Bridge
  instead of PoA 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:

```typescript
// 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`.

> **Note:** When `amount` is `0n` and `feeInclusive` is `false`, minimum amount validation is skipped. This is useful when the exact withdrawal amount is not yet known and you only need a fee estimate.

#### Prefunded Withdrawal Fees

Bridge fees (relayer fee, NEAR storage deposit) are paid in a fee asset: NEAR, or the destination chain's native token for HOT Bridge. By default, when you withdraw any other token, the SDK requests a quote to swap part of the withdrawn token into the fee asset and includes it in `feeEstimation.amount`.

If your account already holds the fee asset, mark the fees as prefunded with `bridgeConfigs`. The SDK then skips the quote, `feeEstimation.amount` is `0n`, and the fees listed in `feeEstimation.underlyingFees` are paid from your fee asset balance. Supported routes: `RouteEnum.HotBridge`, `RouteEnum.OmniBridge`, `RouteEnum.NearWithdrawal` and `RouteEnum.VirtualChain`.

| Option                | Description                                                                          |
|-----------------------|--------------------------------------------------------------------------------------|
| `prefundedFeesTokens` | Asset IDs whose withdrawal fees are prefunded                                        |
| `feesPrefunded`       | When `true`, fees are prefunded for all tokens on the route; `prefundedFeesTokens` is ignored |

```typescript
import {IntentsSDK, RouteEnum} from '@defuse-protocol/intents-sdk';

const sdk = new IntentsSDK({
    referral: 'your-referral-code',
    bridgeConfigs: {
        // Fees prefunded for every token withdrawn via HOT Bridge
        [RouteEnum.HotBridge]: {feesPrefunded: true},
        // Fees prefunded only for the listed tokens; other tokens are still quoted
        [RouteEnum.OmniBridge]: {
            prefundedFeesTokens: ['nep141:usdt.tether-token.near'],
        },
    },
});
```

> **Note:** When the withdrawn asset is the fee asset itself (e.g. `nep141:wrap.near`, or the destination chain's native token for HOT Bridge), the fee is still deducted from the withdrawal and included in `feeEstimation.amount`. The same applies to Omni Bridge UTXO fees (e.g. for BTC withdrawals), which are charged in the withdrawn token.

## Advanced Usage

### Custom RPC URLs

Set NEAR and EVM chains RPC URLs in the constructor:

```typescript
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'],
    }
});
```

### Other Intent Signers

The SDK supports multiple intent signing methods using factory functions:

#### NEAR KeyPair Signer

```typescript
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

```typescript
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

```typescript
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`:

```typescript
// 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](https://github.com/near/intents/tree/main/defuse#nonces) for the structure reflecting their validity.

```typescript
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:

```typescript
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:

```typescript
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.

```typescript
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:

```typescript
// 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:**

```typescript
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:

```typescript
// 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.

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
// 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

```typescript
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.

```typescript
// 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.

```typescript
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.

```typescript
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.

```typescript
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](https://docs.near-intents.org/near-intents/chain-address-support) in the Near Intents
documentation.

## Development

### Prerequisites

- [Node.js](https://nodejs.org/) (v20 or later)
- [pnpm](https://pnpm.io/) for package management

### Setup

```bash
# Install dependencies (from the monorepo root)
pnpm install
```

### Build

```bash
# Build the package
pnpm run build

# Build in watch mode
pnpm run dev
```

### Test

```bash
# Run tests
pnpm run test

# Run tests in watch mode  
pnpm run test:watch
```

### Lint and Format

```bash
# Check code style
pnpm run lint

# Format code
pnpm run format
```

## Version History

See [CHANGELOG.md](./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

---
_Source: https://npm.io/package/@defuse-protocol/intents-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._