@defuse-protocol/one-click-sdk-typescript/dist/index.d.ts

TypeScript SDK for 1Click API

type ApiRequestOptions = {
    readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH';
    readonly url: string;
    readonly path?: Record<string, any>;
    readonly cookies?: Record<string, any>;
    readonly headers?: Record<string, any>;
    readonly query?: Record<string, any>;
    readonly formData?: Record<string, any>;
    readonly body?: any;
    readonly mediaType?: string;
    readonly responseHeader?: string;
    readonly errors?: Record<number, string>;
};

type ApiResult = {
    readonly url: string;
    readonly ok: boolean;
    readonly status: number;
    readonly statusText: string;
    readonly body: any;
};

declare class ApiError extends Error {
    readonly url: string;
    readonly status: number;
    readonly statusText: string;
    readonly body: any;
    readonly request: ApiRequestOptions;
    constructor(request: ApiRequestOptions, response: ApiResult, message: string);
}

declare class CancelError extends Error {
    constructor(message: string);
    get isCancelled(): boolean;
}
interface OnCancel {
    readonly isResolved: boolean;
    readonly isRejected: boolean;
    readonly isCancelled: boolean;
    (cancelHandler: () => void): void;
}
declare class CancelablePromise<T> implements Promise<T> {
    #private;
    constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void, onCancel: OnCancel) => void);
    get [Symbol.toStringTag](): string;
    then<TResult1 = T, TResult2 = never>(onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
    catch<TResult = never>(onRejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
    finally(onFinally?: (() => void) | null): Promise<T>;
    cancel(): void;
    get isCancelled(): boolean;
}

type Resolver<T> = (options: ApiRequestOptions) => Promise<T>;
type Headers = Record<string, string>;
type OpenAPIConfig = {
    BASE: string;
    VERSION: string;
    WITH_CREDENTIALS: boolean;
    CREDENTIALS: 'include' | 'omit' | 'same-origin';
    TOKEN?: string | Resolver<string> | undefined;
    USERNAME?: string | Resolver<string> | undefined;
    PASSWORD?: string | Resolver<string> | undefined;
    HEADERS?: Headers | Resolver<Headers> | undefined;
    ENCODE_PATH?: ((path: string) => string) | undefined;
};
declare const OpenAPI: OpenAPIConfig;

type AppFee = {
    /**
     * Intents Account ID where this fee will be transferred to
     */
    recipient: string;
    /**
     * Fee for this recipient as part of amountIn in basis points (1/100th of a percent), e.g. 100 for 1% fee
     */
    fee: number;
};

type BadRequestResponse = {
    message: string;
};

type Quote = {
    /**
     * The deposit address on the chain of `originAsset` in case if `depositType` is `ORIGIN_CHAIN`.
     *
     * The deposit address inside of near intents (the verifier smart contract) in case if `depositType` is `INTENTS`.
     */
    depositAddress?: string;
    /**
     * Amount of the origin asset
     */
    amountIn: string;
    /**
     * Amount of the origin asset in readable format
     */
    amountInFormatted: string;
    /**
     * Amount of the origin assets equivalent in USD
     */
    amountInUsd: string;
    /**
     * Minimum amount of the origin asset that will be used for swap
     */
    minAmountIn: string;
    /**
     * Amount of the destination asset
     */
    amountOut: string;
    /**
     * Amount of the destination asset in readable format
     */
    amountOutFormatted: string;
    /**
     * Amount of the destination asset equivalent in USD
     */
    amountOutUsd: string;
    /**
     * Minimum amount with slippage taken into account
     */
    minAmountOut: string;
    /**
     * Time when the deposit address will become inactive and funds might be lost
     */
    deadline?: string;
    /**
     * Time when the deposit address will become cold and swap processing will take more time
     */
    timeWhenInactive?: string;
    /**
     * Estimated time in seconds for swap to be executed after the deposit transaction is confirmed
     */
    timeEstimate: number;
    /**
     * EVM address of a transfer recipient in a virtual chain
     */
    virtualChainRecipient?: string;
    /**
     * EVM address of a refund recipient in a virtual chain
     */
    virtualChainRefundRecipient?: string;
};

type QuoteRequest = {
    /**
     * Flag indicating whether this is a dry run request.
     * If `true`, the response will **NOT** contain the following fields:
     * - `depositAddress`
     * - `timeWhenInactive`
     * - `deadline`
     */
    dry: boolean;
    /**
     * Whether to use the amount as the output or the input for the basis of the swap:
     * - `EXACT_INPUT` - request output amount for exact input.
     * - `EXACT_OUTPUT` - request output amount for exact output. The `refundTo` address will always receive excess tokens back even after the swap is complete.
     * - `FLEX_INPUT` - flexible input amount that allows for partial deposits and variable amounts.
     */
    swapType: QuoteRequest.swapType;
    /**
     * Slippage tolerance for the swap. This value is in basis points (1/100th of a percent), e.g. 100 for 1% slippage.
     */
    slippageTolerance: number;
    /**
     * ID of the origin asset.
     */
    originAsset: string;
    /**
     * Type of the deposit address:
     * - `ORIGIN_CHAIN` - deposit address on the origin chain
     * - `INTENTS` - **account ID** inside near intents to which you should transfer assets inside intents.
     */
    depositType: QuoteRequest.depositType;
    /**
     * ID of the destination asset.
     */
    destinationAsset: string;
    /**
     * Amount to swap as the base amount (can be switched to exact input/output using the dedicated flag), denoted in the smallest unit of the specified currency (e.g., wei for ETH).
     */
    amount: string;
    /**
     * Address for user refund.
     */
    refundTo: string;
    /**
     * Type of refund address:
     * - `ORIGIN_CHAIN` - assets will be refunded to `refundTo` address on the origin chain
     * - `INTENTS` - assets will be refunded to `refundTo` intents account
     */
    refundType: QuoteRequest.refundType;
    /**
     * Recipient address. The format should match `recipientType`.
     */
    recipient: string;
    /**
     * EVM address of a transfer recipient in a virtual chain
     */
    virtualChainRecipient?: string;
    /**
     * EVM address of a refund recipient in a virtual chain
     */
    virtualChainRefundRecipient?: string;
    /**
     * Type of recipient address:
     * - `DESTINATION_CHAIN` - assets will be transferred to chain of `destinationAsset`
     * - `INTENTS` - assets will be transferred to account inside intents
     */
    recipientType: QuoteRequest.recipientType;
    /**
     * Timestamp in ISO format, that identifies when user refund will begin if the swap isn't completed by then. It needs to exceed the time required for the deposit tx to be minted, e.g. for Bitcoin it might require ~1h depending on the gas fees paid.
     */
    deadline: string;
    /**
     * Referral identifier(lower case only). It will be reflected in the on-chain data and displayed on public analytics platforms.
     */
    referral?: string;
    /**
     * Time in milliseconds user is willing to wait for quote from relay.
     */
    quoteWaitingTimeMs?: number;
    /**
     * List of recipients and their fees
     */
    appFees?: Array<AppFee>;
};
declare namespace QuoteRequest {
    /**
     * Whether to use the amount as the output or the input for the basis of the swap:
     * - `EXACT_INPUT` - request output amount for exact input.
     * - `EXACT_OUTPUT` - request output amount for exact output. The `refundTo` address will always receive excess tokens back even after the swap is complete.
     * - `FLEX_INPUT` - flexible input amount that allows for partial deposits and variable amounts.
     */
    enum swapType {
        EXACT_INPUT = "EXACT_INPUT",
        EXACT_OUTPUT = "EXACT_OUTPUT",
        FLEX_INPUT = "FLEX_INPUT"
    }
    /**
     * Type of the deposit address:
     * - `ORIGIN_CHAIN` - deposit address on the origin chain
     * - `INTENTS` - **account ID** inside near intents to which you should transfer assets inside intents.
     */
    enum depositType {
        ORIGIN_CHAIN = "ORIGIN_CHAIN",
        INTENTS = "INTENTS"
    }
    /**
     * Type of refund address:
     * - `ORIGIN_CHAIN` - assets will be refunded to `refundTo` address on the origin chain
     * - `INTENTS` - assets will be refunded to `refundTo` intents account
     */
    enum refundType {
        ORIGIN_CHAIN = "ORIGIN_CHAIN",
        INTENTS = "INTENTS"
    }
    /**
     * Type of recipient address:
     * - `DESTINATION_CHAIN` - assets will be transferred to chain of `destinationAsset`
     * - `INTENTS` - assets will be transferred to account inside intents
     */
    enum recipientType {
        DESTINATION_CHAIN = "DESTINATION_CHAIN",
        INTENTS = "INTENTS"
    }
}

type QuoteResponse = {
    /**
     * Timestamp in ISO format that took part in the deposit address derivation
     */
    timestamp: string;
    /**
     * Signature of the 1Click service confirming the quote for the specific deposit address. Must be saved on the client side (along with the whole quote) in order to resolve any disputes or mistakes.
     */
    signature: string;
    /**
     * User request
     */
    quoteRequest: QuoteRequest;
    /**
     * Response that contains the deposit address to send "amount" of `originAsset` and possible output amount.
     */
    quote: Quote;
};

type TransactionDetails = {
    /**
     * Transaction hash
     */
    hash: string;
    /**
     * Explorer URL for the transaction
     */
    explorerUrl: string;
};

type SwapDetails = {
    /**
     * All intent hashes that took part in this swap
     */
    intentHashes: Array<string>;
    /**
     * All Near transactions executed for this swap
     */
    nearTxHashes: Array<string>;
    /**
     * Exact amount of `originToken` after trade was settled
     */
    amountIn?: string;
    /**
     * Exact amount of `originToken` after trade was settled in readable format
     */
    amountInFormatted?: string;
    /**
     * Exact amount of `originToken` equivalent in USD
     */
    amountInUsd?: string;
    /**
     * Exact amount of `destinationToken` after trade was settled
     */
    amountOut?: string;
    /**
     * Exact amount of `destinationToken` in readable format
     */
    amountOutFormatted?: string;
    /**
     * Exact amount of `destinationToken` equivalent in USD
     */
    amountOutUsd?: string;
    /**
     * Actual slippage
     */
    slippage?: number;
    /**
     * Hashes and explorer URLs for all transactions on the origin chain
     */
    originChainTxHashes: Array<TransactionDetails>;
    /**
     * Hashes and explorer URLs for all transactions on the destination chain
     */
    destinationChainTxHashes: Array<TransactionDetails>;
    /**
     * Amount of `originAsset` that got transferred to `refundTo`
     */
    refundedAmount?: string;
    /**
     * Refunded amount in readable format
     */
    refundedAmountFormatted?: string;
    /**
     * Refunded amount equivalent in USD
     */
    refundedAmountUsd?: string;
};

type GetExecutionStatusResponse = {
    /**
     * Quote response from original request
     */
    quoteResponse: QuoteResponse;
    status: GetExecutionStatusResponse.status;
    /**
     * Last time the state was updated
     */
    updatedAt: string;
    /**
     * Details of actual swaps and withdrawals
     */
    swapDetails: SwapDetails;
};
declare namespace GetExecutionStatusResponse {
    enum status {
        KNOWN_DEPOSIT_TX = "KNOWN_DEPOSIT_TX",
        PENDING_DEPOSIT = "PENDING_DEPOSIT",
        INCOMPLETE_DEPOSIT = "INCOMPLETE_DEPOSIT",
        PROCESSING = "PROCESSING",
        SUCCESS = "SUCCESS",
        REFUNDED = "REFUNDED",
        FAILED = "FAILED"
    }
}

type SubmitDepositTxRequest = {
    /**
     * Transaction hash of your deposit
     */
    txHash: string;
    /**
     * Deposit address for the quote
     */
    depositAddress: string;
};

type SubmitDepositTxResponse = {
    /**
     * Quote response from original request
     */
    quoteResponse: QuoteResponse;
    status: SubmitDepositTxResponse.status;
    /**
     * Last time the state was updated
     */
    updatedAt: string;
    /**
     * Details of actual swaps and withdrawals
     */
    swapDetails: SwapDetails;
};
declare namespace SubmitDepositTxResponse {
    enum status {
        KNOWN_DEPOSIT_TX = "KNOWN_DEPOSIT_TX",
        PENDING_DEPOSIT = "PENDING_DEPOSIT",
        INCOMPLETE_DEPOSIT = "INCOMPLETE_DEPOSIT",
        PROCESSING = "PROCESSING",
        SUCCESS = "SUCCESS",
        REFUNDED = "REFUNDED",
        FAILED = "FAILED"
    }
}

type TokenResponse = {
    /**
     * Unique asset identifier
     */
    assetId: string;
    /**
     * Number of decimals for the token
     */
    decimals: number;
    /**
     * Blockchain associated with the token
     */
    blockchain: TokenResponse.blockchain;
    /**
     * Token symbol (e.g. BTC, ETH)
     */
    symbol: string;
    /**
     * Current price of the token in USD
     */
    price: number;
    /**
     * Date when the token price was last updated
     */
    priceUpdatedAt: string;
    /**
     * Contract address of the token
     */
    contractAddress?: string;
};
declare namespace TokenResponse {
    /**
     * Blockchain associated with the token
     */
    enum blockchain {
        NEAR = "near",
        ETH = "eth",
        BASE = "base",
        ARB = "arb",
        BTC = "btc",
        SOL = "sol",
        TON = "ton",
        DOGE = "doge",
        XRP = "xrp",
        ZEC = "zec",
        GNOSIS = "gnosis",
        BERA = "bera",
        BSC = "bsc",
        POL = "pol",
        TRON = "tron",
        SUI = "sui",
        OP = "op",
        AVAX = "avax",
        CARDANO = "cardano"
    }
}

declare class OneClickService {
    /**
     * Get supported tokens
     * Retrieves a list of tokens currently supported by the 1Click API for asset swaps.
     *
     * Each token entry includes its blockchain, contract address (if available), price in USD, and other metadata such as symbol and decimals.
     * @returns TokenResponse
     * @throws ApiError
     */
    static getTokens(): CancelablePromise<Array<TokenResponse>>;
    /**
     * Request a swap quote
     * Generates a swap quote based on input parameters such as the assets, amount, slippage tolerance, and recipient/refund information.
     *
     * Returns pricing details, estimated time, and a unique **deposit address** to which tokens must be transferred to initiate the swap.
     *
     * You can set the `dry` parameter to `true` to simulate the quote request **without generating a deposit address** or initiating the swap process. This is useful for previewing swap parameters or validating input data without committing to an actual swap.
     *
     * This endpoint is the first required step in the swap process.
     * @param requestBody
     * @returns QuoteResponse
     * @throws ApiError
     */
    static getQuote(requestBody: QuoteRequest): CancelablePromise<QuoteResponse>;
    /**
     * Check swap execution status
     * Retrieves the current status of a swap using the unique deposit address from the quote.
     *
     * The response includes the state of the swap (e.g., pending, processing, success, refunded) and any associated swap and transaction details.
     * @param depositAddress
     * @returns GetExecutionStatusResponse
     * @throws ApiError
     */
    static getExecutionStatus(depositAddress: string): CancelablePromise<GetExecutionStatusResponse>;
    /**
     * Submit deposit transaction hash
     * Optionally notifies the 1Click service that a deposit has been sent to the specified address, using the blockchain transaction hash.
     *
     * This step can speed up swap processing by allowing the system to preemptively verify the deposit.
     * @param requestBody
     * @returns SubmitDepositTxResponse
     * @throws ApiError
     */
    static submitDepositTx(requestBody: SubmitDepositTxRequest): CancelablePromise<SubmitDepositTxResponse>;
}

export { ApiError, type AppFee, type BadRequestResponse, CancelError, CancelablePromise, GetExecutionStatusResponse, OneClickService, OpenAPI, type OpenAPIConfig, type Quote, QuoteRequest, type QuoteResponse, type SubmitDepositTxRequest, SubmitDepositTxResponse, type SwapDetails, TokenResponse, type TransactionDetails };