@defuse-protocol/one-click-sdk-typescript
Version:
TypeScript SDK for 1Click API
722 lines (702 loc) • 23.9 kB
TypeScript
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> {
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 AnyInputQuoteWithdrawal = {
/**
* Withdrawal status
*/
status: AnyInputQuoteWithdrawal.status;
/**
* Amount out in readable format
*/
amountOutFormatted: string;
/**
* Amount out in USD
*/
amountOutUsd: string;
/**
* Amount out in smallest unit
*/
amountOut: string;
/**
* Withdrawal fee in readable format
*/
withdrawFeeFormatted: string;
/**
* Withdrawal fee in smallest unit
*/
withdrawFee: string;
/**
* Withdrawal fee in USD
*/
withdrawFeeUsd: string;
/**
* Timestamp of withdrawal
*/
timestamp: string;
/**
* Transaction hash
*/
hash: string;
};
declare namespace AnyInputQuoteWithdrawal {
/**
* Withdrawal status
*/
enum status {
SUCCESS = "SUCCESS",
FAILED = "FAILED"
}
}
type AppFee = {
/**
* Account ID within Intents to which this fee will be transferred
*/
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 GetAnyInputQuoteWithdrawals = {
/**
* ID of the destination asset.
*/
asset: string;
/**
* Recipient address
*/
recipient: string;
/**
* Affiliate recipient address
*/
affiliateRecipient: string;
/**
* Details of withdrawals
*/
withdrawals?: AnyInputQuoteWithdrawal;
};
type Quote = {
/**
* The deposit address on the chain of `originAsset` when `depositType` is `ORIGIN_CHAIN`.
*
* The deposit address inside NEAR Intents (the verifier smart contract) when `depositType` is `INTENTS`.
*/
depositAddress?: string;
/**
* Some of the deposit addresses **REQUIRE** to also include the `memo` for the deposit to be processed
*/
depositMemo?: 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 the 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 output amount after slippage is applied
*/
minAmountOut: string;
/**
* Time when the deposit address becomes inactive and funds may be lost
*/
deadline?: string;
/**
* Time when the deposit address becomes cold, causing swap processing to take longer
*/
timeWhenInactive?: string;
/**
* Estimated time in seconds for the 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;
/**
* **HIGHLY EXPERIMENTAL** Message passed to `ft_transfer_call` when withdrawing assets to NEAR.
*
* Otherwise, `ft_transfer` will be used.
*
* **WARNING**: Funds will be lost if used with non NEP-141 tokens, in case of insufficient `storage_deposit` or if the recipient does not implement `ft_on_transfer` method.
*/
customRecipientMsg?: 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;
/**
* What deposit address mode you will get in the response, most chain supports only `SIMPLE` and some(for example `stellar`) only `MEMO`:
* - `SIMPLE` - usual deposit with only deposit address.
* - `MEMO` - some chains will **REQUIRE** the `memo` together with `depositAddress` for swap to work.
*/
depositMode?: QuoteRequest.depositMode;
/**
* How to interpret `amount` (and refunds) when performing the swap:
*
* - `EXACT_INPUT` — requests the output amount for an exact input.
* - If deposit is less than `amountIn`, the deposit is refunded by deadline.
* - If deposit is above than `amountIn`, the swap is processed and the excess is refunded to `refundTo` address after swap is complete.
*
* - `EXACT_OUTPUT` — requests the input amount for an exact output.
* - The quote response would have two fields `minAmountIn` and `maxAmountIn`.
* - If the input is above than `maxAmountIn` the swap is processed and the excess is refunded to `refundTo` address after swap is complete.
* - If the input is less than `minAmountIn`, the deposit is refunded by deadline.
*
* - `FLEX_INPUT` — a flexible input amount that allows for partial deposits and variable amounts.
* - `slippage` applies both to `amountOut` and `amountIn` and defines an acceptable range (`minAmountIn` and `minAmountOut`).
* - Any amount higher than `minAmountIn` is accepted and converted to the output asset as long as `minAmountOut` is met.
* - The `amountIn` can be less, as long as the 'slippage + 1%' constraint is met. If the total received by the deadline is below the lower bound, the deposit is refunded.
* - If deposits exceed the upper bound, the swap is still processed
*/
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 deposit address:
* - `ORIGIN_CHAIN` - deposit address on the origin chain.
* - `INTENTS` - the account ID within NEAR Intents to which you should transfer assets.
*/
depositType: QuoteRequest.depositType;
/**
* ID of the destination asset.
*/
destinationAsset: string;
/**
* Amount to swap as the base amount. It is interpreted as the input or output amount based on the `swapType` flag and is specified in the smallest unit of the currency (e.g., wei for ETH).
*/
amount: string;
/**
* Address used for refunds.
*/
refundTo: string;
/**
* Type of refund address:
* - `ORIGIN_CHAIN` - assets are refunded to the `refundTo` address on the origin chain.
* - `INTENTS` - assets are refunded to the `refundTo` Intents account.
*/
refundType: QuoteRequest.refundType;
/**
* Recipient address. The format must match `recipientType`.
*/
recipient: string;
/**
* Addresses of connected wallets.
*/
connectedWallets?: Array<string>;
/**
* Unique client session identifier for 1Click.
*/
sessionId?: 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;
/**
* **HIGHLY EXPERIMENTAL** Message to pass to `ft_transfer_call` when withdrawing assets to NEAR.
*
* Otherwise, `ft_transfer` will be used.
*
* **WARNING**: Funds will be lost if used with non NEP-141 tokens, in case of insufficient `storage_deposit` or if the recipient does not implement `ft_on_transfer` method.
*/
customRecipientMsg?: string;
/**
* Type of recipient address:
* - `DESTINATION_CHAIN` - assets are transferred to the chain of `destinationAsset`.
* - `INTENTS` - assets are transferred to an account inside Intents
*/
recipientType: QuoteRequest.recipientType;
/**
* Timestamp in ISO format that identifies when the user refund begins if the swap isn't completed by then. It must exceed the time required for the deposit transaction to be mined. For example, Bitcoin may require around one hour depending on the fees paid.
*/
deadline: string;
/**
* Referral identifier (lowercase only). It will be reflected in the on-chain data and displayed on public analytics platforms.
*/
referral?: string;
/**
* Time in milliseconds the user is willing to wait for a quote from the relay.
* **If you want to receive the fastest quote - use `0` as a value**
*/
quoteWaitingTimeMs?: number;
/**
* List of recipients and their fees
*/
appFees?: Array<AppFee>;
};
declare namespace QuoteRequest {
/**
* What deposit address mode you will get in the response, most chain supports only `SIMPLE` and some(for example `stellar`) only `MEMO`:
* - `SIMPLE` - usual deposit with only deposit address.
* - `MEMO` - some chains will **REQUIRE** the `memo` together with `depositAddress` for swap to work.
*/
enum depositMode {
SIMPLE = "SIMPLE",
MEMO = "MEMO"
}
/**
* How to interpret `amount` (and refunds) when performing the swap:
*
* - `EXACT_INPUT` — requests the output amount for an exact input.
* - If deposit is less than `amountIn`, the deposit is refunded by deadline.
* - If deposit is above than `amountIn`, the swap is processed and the excess is refunded to `refundTo` address after swap is complete.
*
* - `EXACT_OUTPUT` — requests the input amount for an exact output.
* - The quote response would have two fields `minAmountIn` and `maxAmountIn`.
* - If the input is above than `maxAmountIn` the swap is processed and the excess is refunded to `refundTo` address after swap is complete.
* - If the input is less than `minAmountIn`, the deposit is refunded by deadline.
*
* - `FLEX_INPUT` — a flexible input amount that allows for partial deposits and variable amounts.
* - `slippage` applies both to `amountOut` and `amountIn` and defines an acceptable range (`minAmountIn` and `minAmountOut`).
* - Any amount higher than `minAmountIn` is accepted and converted to the output asset as long as `minAmountOut` is met.
* - The `amountIn` can be less, as long as the 'slippage + 1%' constraint is met. If the total received by the deadline is below the lower bound, the deposit is refunded.
* - If deposits exceed the upper bound, the swap is still processed
*/
enum swapType {
EXACT_INPUT = "EXACT_INPUT",
EXACT_OUTPUT = "EXACT_OUTPUT",
FLEX_INPUT = "FLEX_INPUT",
ANY_INPUT = "ANY_INPUT"
}
/**
* Type of deposit address:
* - `ORIGIN_CHAIN` - deposit address on the origin chain.
* - `INTENTS` - the account ID within NEAR Intents to which you should transfer assets.
*/
enum depositType {
ORIGIN_CHAIN = "ORIGIN_CHAIN",
INTENTS = "INTENTS"
}
/**
* Type of refund address:
* - `ORIGIN_CHAIN` - assets are refunded to the `refundTo` address on the origin chain.
* - `INTENTS` - assets are refunded to the `refundTo` Intents account.
*/
enum refundType {
ORIGIN_CHAIN = "ORIGIN_CHAIN",
INTENTS = "INTENTS"
}
/**
* Type of recipient address:
* - `DESTINATION_CHAIN` - assets are transferred to the chain of `destinationAsset`.
* - `INTENTS` - assets are transferred to an account inside Intents
*/
enum recipientType {
DESTINATION_CHAIN = "DESTINATION_CHAIN",
INTENTS = "INTENTS"
}
}
type QuoteResponse = {
/**
* Unique identifier for request tracing and debugging
*/
correlationId: string;
/**
* Timestamp in ISO format that was used to derive the deposit address
*/
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 containing the deposit address for sending the `amount` of `originAsset` and the expected 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 the trade was settled
*/
amountIn?: string;
/**
* Exact amount of `originToken` in readable format after the trade was settled
*/
amountInFormatted?: string;
/**
* Exact amount of `originToken` equivalent in USD
*/
amountInUsd?: string;
/**
* Exact amount of `destinationToken` after the trade was settled
*/
amountOut?: string;
/**
* Exact amount of `destinationToken` in readable format after the trade was settled
*/
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` transferred to `refundTo`
*/
refundedAmount?: string;
/**
* Refunded amount in readable format
*/
refundedAmountFormatted?: string;
/**
* Refunded amount equivalent in USD
*/
refundedAmountUsd?: string;
/**
* Reason for refund
*/
refundReason?: string;
/**
* Amount deposited to `depositAddress` onchain
*/
depositedAmount?: string;
/**
* Amount deposited in readable format
*/
depositedAmountFormatted?: string;
/**
* Amount deposited equivalent in USD
*/
depositedAmountUsd?: string;
/**
* Referral identifier
*/
referral?: string;
};
type GetExecutionStatusResponse = {
/**
* Unique identifier for request tracing and debugging
*/
correlationId: string;
/**
* Quote response from the 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;
/**
* Sender account (used only for NEAR blockchain)
*/
nearSenderAccount?: string;
/**
* Memo (use if deposit was submitted with one)
*/
memo?: string;
};
type SubmitDepositTxResponse = {
/**
* Unique identifier for request tracing and debugging
*/
correlationId: string;
/**
* Quote response from the 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",
LTC = "ltc",
XLAYER = "xlayer",
MONAD = "monad",
BCH = "bch",
ADI = "adi",
STARKNET = "starknet"
}
}
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, if quote response included deposit memo, it is required as well.
*
* The response includes the state of the swap (e.g., pending, processing, success, refunded) and any associated swap and transaction details.
* @param depositAddress
* @param depositMemo
* @returns GetExecutionStatusResponse
* @throws ApiError
*/
static getExecutionStatus(depositAddress: string, depositMemo?: string): CancelablePromise<GetExecutionStatusResponse>;
/**
* Get ANY_INPUT withdrawals
* Retrieves all withdrawals by ANY_INPUT quote with filtering, pagination and sorting
* @param depositAddress
* @param depositMemo
* @param timestampFrom Filter withdrawals from this timestamp (ISO string)
* @param page Page number for pagination (default: 1)
* @param limit Number of withdrawals per page (max: 50, default: 50)
* @param sortOrder Sort order
* @returns GetAnyInputQuoteWithdrawals
* @throws ApiError
*/
static getAnyInputQuoteWithdrawals(depositAddress: string, depositMemo?: string, timestampFrom?: string, page?: number, limit?: number, sortOrder?: 'asc' | 'desc'): CancelablePromise<GetAnyInputQuoteWithdrawals>;
/**
* 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 { AnyInputQuoteWithdrawal, ApiError, type AppFee, type BadRequestResponse, CancelError, CancelablePromise, type GetAnyInputQuoteWithdrawals, GetExecutionStatusResponse, OneClickService, OpenAPI, type OpenAPIConfig, type Quote, QuoteRequest, type QuoteResponse, type SubmitDepositTxRequest, SubmitDepositTxResponse, type SwapDetails, TokenResponse, type TransactionDetails };