stableflow-ai-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,549 @@
+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 = {
+    /**
+     * 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 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;
+};
+
+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` when performing the swap:
+     * - `EXACT_INPUT` - requests the output amount for an exact input.
+     * - `EXACT_OUTPUT` - requests the input amount for an exact output. The `refundTo` address always receives any excess tokens after the swap is complete.
+     * - `FLEX_INPUT` - a 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 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;
+    /**
+     * 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 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.
+     */
+    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` when performing the swap:
+     * - `EXACT_INPUT` - requests the output amount for an exact input.
+     * - `EXACT_OUTPUT` - requests the input amount for an exact output. The `refundTo` address always receives any excess tokens after the swap is complete.
+     * - `FLEX_INPUT` - a 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 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 = {
+    /**
+     * Timestamp in ISO format that was used to derive the deposit address
+     */
+    timestamp: string;
+    /**
+     * Signature of the StableFlow 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;
+};
+
+type GetExecutionStatusResponse = {
+    /**
+     * 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;
+};
+
+type SubmitDepositTxResponse = {
+    /**
+     * 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"
+    }
+}
+
+/**
+ * StableFlow AI Service
+ * Main service class for interacting with the StableFlow AI API
+ */
+declare class SFA {
+    /**
+     * Get supported tokens
+     * Retrieves a list of tokens currently supported by the StableFlow AI 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>;
+    /**
+     * Submit deposit transaction hash
+     * Optionally notifies the StableFlow AI 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, OpenAPI, type OpenAPIConfig, type Quote, QuoteRequest, type QuoteResponse, SFA, type SubmitDepositTxRequest, SubmitDepositTxResponse, type SwapDetails, TokenResponse, type TransactionDetails };