@defuse-protocol/one-click-sdk-typescript

One Click SDK - TypeScript

A powerful TypeScript SDK for seamless cross-chain token swaps using the 1Click API. Built with type safety in mind, this SDK enables developers to easily integrate cross-chain swapping functionality into their applications with minimal setup.

Prerequisites

• Node.js >= 16
• pnpm >= 8 (For SDK Developers not users)

Installation

# Using npm
npm install @defuse-protocol/one-click-sdk-typescript

# Using yarn
yarn add @defuse-protocol/one-click-sdk-typescript

# Using pnpm
pnpm add @defuse-protocol/one-click-sdk-typescript

Quick Start

import { OpenAPI, QuoteRequest, OneClickService } from '@defuse-protocol/one-click-sdk-typescript';

// Initialize the API client
OpenAPI.BASE = 'https://1click.chaindefuser.com';

// Configure your JSON Web Token (JWT) - required for most endpoints
// Request one here:
// https://docs.google.com/forms/d/e/1FAIpQLSdrSrqSkKOMb_a8XhwF0f7N5xZ0Y5CYgyzxiAuoC2g4a2N68g/viewform
OpenAPI.TOKEN = "your-JSON-Web-Token";

// Create a quote request
// See docs for more info:
// https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api#post-v0-quote
const quoteRequest: QuoteRequest = {
    dry: true, // set to true for testing / false to get `depositAddress` and execute swap
    swapType: QuoteRequest.swapType.EXACT_INPUT,
    slippageTolerance: 100, // 1%
    originAsset: 'nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near', // USDC on Arbitrum
    depositType: QuoteRequest.depositType.ORIGIN_CHAIN,
    destinationAsset: 'nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near', // USDC on Solana
    amount: '1000000', // 1 USDC (in smallest units)
    refundTo: '0x2527D02599Ba641c19FEa793cD0F167589a0f10D', // Valid Arbitrum address
    refundType: QuoteRequest.refundType.ORIGIN_CHAIN, 
    recipient: '13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK', // Valid Solana Address
    recipientType: QuoteRequest.recipientType.DESTINATION_CHAIN,
    deadline: "2025-08-06T14:15:22Z"
};

// Get quote
const quote = await OneClickService.getQuote(quoteRequest);

API Methods

See official API docs for more info on endpoints.

Get Quote

const quote = await OneClickService.getQuote(quoteRequest);

Get Execution Status

const status = await OneClickService.getExecutionStatus(depositAddress);

Submit Deposit Transaction

const result = await OneClickService.submitDepositTx({
    txHash: '0x...',
    depositAddress: '0x...'
});

Authentication

The 1Click API requires JWT authentication for most endpoints -> Request yours here

Static Token (Required)

// Set a static JWT - required for authenticated endpoints
OpenAPI.TOKEN = 'your-JSON-Web-Token';

Dynamic Token Provider (for token refresh)

// Set a function that returns a fresh token when needed
OpenAPI.TOKEN = async () => {
  // Get a fresh token from your authentication system
  return 'FRESH_JWT';
};

Protected Endpoints

The following endpoints require JWT authentication:

• OneClickService.getQuote()
• OneClickService.submitDepositTx()
• OneClickService.getExecutionStatus()

Error Handling

The SDK throws typed errors that you can catch and handle:

try {
    const quote = await OneClickService.getQuote(quoteRequest);
} catch (error) {
    if (error instanceof ApiError && error.status === 401) {
        // Handle authentication errors
        console.error('Authentication failed: JWT is missing or invalid');
    } else if (error instanceof ApiError && error.status === 400) {
        // Handle bad request
        console.error('Invalid request:', error.body);
    } else {
        // Handle other errors
        console.error('Error:', error);
    }
}

License

ISC - See LICENSE for details.

For Developers

For SDK developers (not SDK users), here are the development commands:

# Install dependencies
pnpm install

# Generate fresh SDK from latest API spec
pnpm generate:fresh

# Build the SDK
pnpm build

# Clean build artifacts
pnpm clean