@hot-pot/hotpot-sdk-ts 0.0.1

package/examples/intent/main.ts

@@ -0,0 +1,82 @@
+import { HotPotApiClient } from '../../src/apiClient.js';
+import { preparePermit2Approval } from '../../src/approvals.js';
+import { SwapType } from '../../src/types.js';
+
+async function main() {
+    // Initialize the HotPot API client with the API key from environment variables
+    const apiKey = process.env['API_KEY'];
+    if (!apiKey) {
+        throw new Error('API_KEY environment variable is not set');
+    }
+
+    const client = new HotPotApiClient('https://api.hotpot.com/affiliate/v1', apiKey);
+
+    // Example parameters for getting a quote
+    const sourceChain = 1; // Ethereum mainnet
+    const sourceToken = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC token address
+    const destChain = 1; // Ethereum mainnet
+    const destToken = '0x2791Bca1f2de4661ED88A3C59D7D5E7383a7f9D7'; // USDC token address on Polygon
+    const amount = 1_000_000; // Amount in USD (or base units depending on token)
+    const slippageBps = 50n; // 0.5% slippage
+    const swapType = SwapType.Optimized;
+
+    // Get a quote for the swap
+    console.log('Getting quote...');
+    const quote = await client.getQuote(
+        sourceChain,
+        sourceToken,
+        destChain,
+        destToken,
+        amount,
+        slippageBps,
+        swapType,
+    );
+    console.log('Quote received:', quote);
+
+    // Example user addresses
+    const userSourceAddress = '0xUserSourceAddress';
+    const userDestinationAddress = '0xUserDestinationAddress';
+    const refundAddress = '0xRefundAddress';
+
+    // Create an intent based on the quote
+    console.log('Creating intent...');
+    const intentData = await client.createIntent(
+        quote.id,
+        null, // userSourcePublicKey (null for EVM)
+        userSourceAddress,
+        userDestinationAddress,
+        refundAddress,
+    );
+    console.log('Intent created:', intentData);
+
+    // Prepare the permit2 approval for signing
+    const permit2Approval = preparePermit2Approval(
+        intentData.params_to_sign as any, // Cast to Permit2ApprovalToSign
+        quote,
+        userSourceAddress,
+        intentData.deadline_secs,
+    );
+    console.log('Permit2 approval prepared:', permit2Approval);
+
+    // In a real scenario, you would sign the permit2Approval here using a wallet
+    // For example: const signature = await wallet.signTypedData(permit2Approval);
+    // For this example, we'll simulate a signed approval
+    const signedApproval = {
+        type: 'permit2' as const,
+        signed_data: '0xSimulatedSignature', // Replace with actual signature in production
+    };
+
+    // Add the approval to the intent
+    console.log('Adding approval...');
+    await client.addApproval(signedApproval, intentData.intent_id);
+    console.log('Approval added');
+
+    // Get the current status of the intent
+    console.log('Getting intent status...');
+    const status = await client.getIntentStatus(intentData.intent_id);
+    console.log('Intent status:', status);
+}
+
+await main()
+    .then(() => console.log('Example completed'))
+    .catch(console.error);

package/examples/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "extends": "../tsconfig.json",
+    "include": ["./"],
+    "compilerOptions": {
+        "noEmit": true,
+    },
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@hot-pot/hotpot-sdk-ts",
+    "private": false,
+    "version": "0.0.1",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist",
+    "files": [
+        "**"
+    ],
+    "types": "./dist/index.d.ts",
+    "dependencies": {
+        "axios": "^1.13.4",
+        "viem": "^2.45.0"
+    },
+    "scripts": {
+        "build": "rm -rf dist && tsc",
+        "lint": "eslint . --ext .ts",
+        "lint:fix": "eslint . --ext .ts --fix",
+        "prettier": "prettier --ignore-path .prettierignore --write \"src/**/*.ts\""
+    },
+    "devDependencies": {
+        "@eslint/js": "9.25.1",
+        "@types/bun": "latest",
+        "@types/node": "22.15.16",
+        "@types/react": "19.0.10",
+        "@types/react-dom": "19.0.4",
+        "@typescript-eslint/eslint-plugin": "8.31.0",
+        "@typescript-eslint/parser": "8.31.0",
+        "@vitejs/plugin-react": "4.3.4",
+        "eslint": "9.25.1",
+        "eslint-plugin-prettier": "5.2.6",
+        "eslint-plugin-simple-import-sort": "12.1.1",
+        "eslint-plugin-unicorn": "58.0.0",
+        "eslint-plugin-unused-imports": "4.1.4",
+        "typescript-eslint": "8.26.1",
+        "jiti": "2.4.2"
+    },
+    "peerDependencies": {
+        "typescript": "^5.0.0"
+    }
+}

package/src/apiClient.ts

@@ -0,0 +1,208 @@
+import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import axios from 'axios';
+
+import type {
+    CreateIntentData,
+    IntentStatus,
+    Network,
+    PaginatedResponse,
+    PublicSwapWithAdditionalInfo,
+    Quote,
+    SignedApproval,
+    SwapType,
+    Token,
+} from './types';
+
+export class HotPotApiClient {
+    private client: AxiosInstance;
+
+    constructor(
+        apiUrl: string,
+        apiKey: string,
+        axiosInstance?: AxiosInstance,
+        config?: AxiosRequestConfig,
+    ) {
+        this.client =
+            axiosInstance ||
+            axios.create({
+                baseURL: apiUrl,
+                headers: {
+                    'x-api-key': apiKey,
+                },
+                ...config,
+            });
+    }
+
+    /**
+     * Fetches the best quote for a swap based on the given parameters
+     * @param sourceChain The source chain ID
+     * @param sourceToken The source token address
+     * @param destChain The destination chain ID
+     * @param destToken The destination token address
+     * @param amount The amount to swap
+     * @param slippageBps The slippage in basis points
+     * @param swapType The type of swap
+     * @param retailUserId Optional retail user ID
+     * @returns A promise that resolves to the Quote object
+     */
+    async getQuote(
+        sourceChain: number,
+        sourceToken: string,
+        destChain: number,
+        destToken: string,
+        amount: number,
+        slippageBps: bigint,
+        swapType: SwapType,
+        retailUserId: string | null = null,
+    ): Promise<Quote> {
+        const response: AxiosResponse<Quote> = await this.client.post('/quotes/best', {
+            source_chain: sourceChain,
+            source_token: sourceToken,
+            dest_chain: destChain,
+            dest_token: destToken,
+            amount,
+            slippage_bps: slippageBps.toString(),
+            swap_type: swapType,
+            retail_user_id: retailUserId,
+        });
+
+        return response.data;
+    }
+
+    /**
+     * Creates a new swap intent with the provided details
+     * @param quoteId The quote ID to use for the intent
+     * @param userSourcePublicKey The user's source public key
+     * @param userSourceAddress The user's source address
+     * @param userDestinationAddress The user's destination address
+     * @param refundAddress The refund address
+     * @returns A promise that resolves to the CreateIntentData object
+     */
+    async createIntent(
+        quoteId: string,
+        userSourcePublicKey: string | null,
+        userSourceAddress: string,
+        userDestinationAddress: string,
+        refundAddress: string,
+    ): Promise<CreateIntentData> {
+        const response: AxiosResponse<CreateIntentData> = await this.client.post('/intents', {
+            quote_id: quoteId,
+            user_source_public_key: userSourcePublicKey,
+            user_source_address: userSourceAddress,
+            user_destination_address: userDestinationAddress,
+            refund_address: refundAddress,
+        });
+
+        return response.data;
+    }
+
+    /**
+     * Adds an approval signature for a specific intent
+     * @param signedData The signed approval data
+     * @param intentId The intent ID to add the approval to
+     */
+    async addApproval(signedData: SignedApproval, intentId: string): Promise<void> {
+        await this.client.post(`/intents/${intentId}/approvals`, signedData);
+    }
+
+    /**
+     * Retrieves details of a specific intent
+     * @param intentId The intent ID to retrieve
+     * @returns A promise that resolves to the PublicSwapWithAdditionalInfo object
+     */
+    async getIntent(intentId: string): Promise<PublicSwapWithAdditionalInfo> {
+        const response: AxiosResponse<PublicSwapWithAdditionalInfo> = await this.client.get(
+            `/intents/${intentId}`,
+        );
+
+        return response.data;
+    }
+
+    /**
+     * Gets the current status of a specific intent
+     * @param intentId The intent ID to check
+     * @returns A promise that resolves to the IntentStatus
+     */
+    async getIntentStatus(intentId: string): Promise<IntentStatus> {
+        const response: AxiosResponse<{ status: IntentStatus }> = await this.client.get(
+            `/intents/${intentId}/status`,
+        );
+
+        return response.data.status;
+    }
+
+    /**
+     * Lists the swap history for a retail user or wallet address
+     * @param walletAddressOrRetailId The wallet address or retail ID
+     * @param limit The maximum number of results to return (default: 20)
+     * @param offset The offset for pagination (default: 0)
+     * @param active Whether to show only active swaps (default: false)
+     * @returns A promise that resolves to a paginated response of PublicSwapWithAdditionalInfo objects
+     */
+    async listRetailUserHistory(
+        walletAddressOrRetailId: string,
+        limit: number = 20,
+        offset: number = 0,
+        active: boolean = false,
+    ): Promise<PaginatedResponse<PublicSwapWithAdditionalInfo>> {
+        const response: AxiosResponse<PaginatedResponse<PublicSwapWithAdditionalInfo>> =
+            await this.client.get(
+                `/swaps/history/${walletAddressOrRetailId}?limit=${limit}&offset=${offset}&active=${active}`,
+            );
+
+        return response.data;
+    }
+
+    /**
+     * Retrieves swap details by intent ID
+     * @param intentId The intent ID to retrieve swap details for
+     * @returns A promise that resolves to the PublicSwapWithAdditionalInfo object
+     */
+    async getSwapByIntentId(intentId: string): Promise<PublicSwapWithAdditionalInfo> {
+        const response: AxiosResponse<PublicSwapWithAdditionalInfo> = await this.client.get(
+            `/swaps/intents/${intentId}`,
+        );
+
+        return response.data;
+    }
+
+    /**
+     * Lists available networks, optionally filtered by token
+     * @param token Optional token to filter networks by
+     * @returns A promise that resolves to an array of Network objects
+     */
+    async listNetworks(token?: string): Promise<Network[]> {
+        const endpoint = token ? `/networks?token=${token}` : '/networks';
+        const response: AxiosResponse<Network[]> = await this.client.get(endpoint);
+
+        return response.data;
+    }
+
+    /**
+     * Lists available tokens with pagination and optional filtering
+     * @param limit The maximum number of results to return (default: 20)
+     * @param offset The offset for pagination (default: 0)
+     * @param q Optional search query
+     * @param networkId Optional network ID to filter by
+     * @returns A promise that resolves to a paginated response of Token objects
+     */
+    async listTokens(
+        limit: number = 20,
+        offset: number = 0,
+        q?: string,
+        networkId?: number,
+    ): Promise<PaginatedResponse<Token>> {
+        let endpoint = `/tokens?limit=${limit}&offset=${offset}`;
+        if (q) {
+            endpoint += `&q=${q}`;
+        }
+        if (networkId) {
+            endpoint += `&network_id=${networkId}`;
+        }
+        const response: AxiosResponse<PaginatedResponse<Token>> = await this.client.get(endpoint);
+
+        return response.data;
+    }
+}
+
+export default HotPotApiClient;

package/src/approvals.ts

@@ -0,0 +1,57 @@
+import { type Permit2ApprovalToSign, type Quote } from './types.js';
+
+export interface SignTypedDataParams {
+    domain: {
+        name: string;
+        version?: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: Record<string, Array<{ name: string; type: string }>>;
+    primaryType: string;
+    message: Record<string, any>;
+    account: string;
+}
+
+/**
+ * Prepares a permit2 approval for signing via EIP-712.
+ * @param permit2Approval The approval which has to be signed
+ * @param quote The quote on which the intent is based
+ * @param userAddress Address of the user creating the intent
+ * @param deadline The deadline in which the swap must be fulfilled
+ */
+export const preparePermit2Approval = (
+    permit2Approval: Permit2ApprovalToSign,
+    quote: Quote,
+    userAddress: string,
+    deadline: number,
+): SignTypedDataParams => {
+    const permit2Data = permit2Approval.additional_data;
+    const domain = {
+        name: permit2Data.domain.name,
+        version: permit2Data.domain.version ?? undefined,
+        chainId: permit2Data.domain.chain_id,
+        verifyingContract: permit2Data.domain.verifying_contract,
+    };
+
+    const witness = permit2Data.witness;
+
+    const message = {
+        permitted: {
+            token: quote.source_token,
+            amount: BigInt(quote.source_amount_lots),
+        },
+        spender: permit2Approval.escrow_contract_address,
+        nonce: permit2Approval.nonce,
+        deadline,
+        witness,
+    };
+
+    return {
+        domain,
+        types: permit2Data.types,
+        primaryType: 'PermitWitnessTransferFrom',
+        message,
+        account: userAddress,
+    };
+};

package/src/errors.ts

@@ -0,0 +1,23 @@
+import type { ApiEntity } from './types.js';
+
+export interface ApiError {
+    code: number;
+    entity: ApiEntity;
+    message: string;
+}
+
+export const API_ERROR_CODES = {
+    INSUFFICIENT_ALLOWANCE: 25,
+} as const;
+
+export class InsufficientAllowanceError extends Error {
+    code: number;
+    entity: string;
+
+    constructor(apiError: ApiError) {
+        super(apiError.message);
+        this.name = 'InsufficientAllowanceError';
+        this.code = apiError.code;
+        this.entity = apiError.entity;
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './apiClient.js';
+export * from './approvals.js';
+export * from './errors.js';
+export * from './types.js';

package/src/types.ts

@@ -0,0 +1,176 @@
+export enum SwapType {
+    Standard = 'standard',
+    Optimized = 'optimized',
+}
+
+export enum IntentStatus {
+    Initiated = 'Initiated',
+    ApprovalAdded = 'ApprovalAdded',
+    Accepted = 'Accepted',
+    Declined = 'Declined',
+    DeclinedDueToKytCheck = 'DeclinedDueToKytCheck',
+    UserDeposited = 'UserDeposited',
+    KycRequested = 'KycRequested',
+    Fulfilled = 'Fulfilled',
+    Expired = 'Expired',
+    RefundRequested = 'RefundRequested',
+    Refunded = 'Refunded',
+}
+
+export enum NetworkType {
+    EVM = 'EVM',
+    TRON = 'TRON',
+    BITCOIN = 'BITCOIN',
+    SOLANA = 'SOLANA',
+}
+
+export interface Quote {
+    id: string;
+    resolver_id: string;
+    source_chain: number;
+    source_token: string;
+    dest_chain: number;
+    dest_token: string;
+    intermediate_token: string | null;
+    intermediate_token_amount_min: string | null;
+    intermediate_token_amount_max: string | null;
+    intermediate_token_decimals: number | null;
+    source_amount_lots: string;
+    source_amount_decimals: number;
+    min_dest_amount_lots: string;
+    max_dest_amount_lots: string;
+    dest_amount_decimals: number;
+    slippage_bps: string;
+    expiry: number;
+    swap_type: SwapType;
+}
+
+export interface CreateIntentData {
+    intent_id: string;
+    deadline_secs: number;
+    secret_hash: `0x${string}`;
+    approval_mechanism: 'permit2' | 'htlc' | 'cosign';
+    params_to_sign: Permit2ApprovalToSign | HtlcApprovalToSign | CosignApprovalToSign;
+}
+
+export type ApprovalType = 'permit2' | 'psbt' | 'cosign';
+
+export interface CosignData {
+    transaction: string;
+    user_address: string;
+}
+
+export interface SignedApproval {
+    type: ApprovalType;
+    signed_data: string | Record<string, string>;
+}
+
+export interface Permit2ApprovalToSign {
+    escrow_contract_address: string;
+    permit2_contract_address: string;
+    resolver_deposit_address: string;
+    nonce: number;
+    additional_data: {
+        domain: {
+            name: string;
+            version: string | null;
+            chain_id: number;
+            verifying_contract: `0x${string}`;
+        };
+        types: Record<string, Array<{ name: string; type: string }>>;
+        witness: Record<string, unknown>;
+        witness_type_string: string;
+        witness_hash: `0x${string}`;
+    };
+}
+
+export interface HtlcApprovalToSign {
+    psbt: string;
+    inputs: number[];
+}
+
+export interface CosignApprovalToSign {
+    transaction: string;
+}
+
+export interface IntentStatusResponse {
+    status: IntentStatus;
+}
+
+export interface PublicSwapWithAdditionalInfo {
+    intent_id: string;
+    status: IntentStatus;
+    kyc_link: string | null;
+    swap_metadata: SwapMetadata | null;
+    source_amount_decimals: number;
+    source_amount_lots: string;
+    source_chain: number;
+    source_token: string;
+    dest_amount_decimals: number;
+    dest_chain: number;
+    dest_token: string;
+    min_dest_amount_lots: string;
+    max_dest_amount_lots: string;
+}
+
+export interface SwapMetadata {
+    id: string;
+    proxy_address: string;
+    user_deposit_tx: string | null;
+    fulfill_tx: string | null;
+    swap_tx: string | null;
+    created_at: Date;
+    user_deposited_at: Date | null;
+    kyc_requested_at: Date | null;
+    fulfilled_at: Date | null;
+    withdrawn_at: Date | null;
+    swapped_at: Date | null;
+    refunded_at: Date | null;
+}
+
+export interface PaginatedResponse<T> {
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        pages: number;
+    };
+    data: T[];
+}
+
+export interface Network {
+    id: number;
+    name: string;
+    type: NetworkType;
+    supports_optimized_swap: boolean;
+    icon_url: string;
+    supports_custom_tokens: boolean;
+}
+
+export interface Token {
+    network_id: number;
+    name: string;
+    contract_address: string;
+    symbol: string;
+    icon_url: string;
+    wrapped_token_address: string | null;
+}
+
+export type ApiEntity =
+    | 'Approval'
+    | 'Intent'
+    | 'Network'
+    | 'Quote'
+    | 'Resolver'
+    | 'SupportedToken'
+    | 'Swap'
+    | 'Token'
+    | 'UserNonce'
+    | 'Transaction'
+    | 'TransactionReceipt'
+    | 'InternalEvent'
+    | 'BlockchainEvent'
+    | 'WatcherRequest'
+    | 'Webhooks'
+    | 'Affiliate'
+    | 'Other';

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+    "compilerOptions": {
+        // Enable latest features
+        "lib": ["ESNext", "DOM"],
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleDetection": "force",
+        "allowJs": true,
+        "outDir": "./dist",
+
+        "baseUrl": "./src",
+
+        // Bundler mode
+        "moduleResolution": "bundler",
+        "verbatimModuleSyntax": true,
+
+        // Best practices
+        "strict": true,
+        "skipLibCheck": true,
+        "noFallthroughCasesInSwitch": true,
+
+        // Some stricter flags (disabled by default)
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "noPropertyAccessFromIndexSignature": false,
+
+        // declarations stuff
+        "declaration": true,
+        "declarationDir": "./dist",
+    },
+    "include": ["src"],
+}