@vaultkey/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,512 @@
+type VaultKeyResponse<T> = {
+    data: T | null;
+    error: ErrorResponse | null;
+};
+type ErrorResponse = {
+    message: string;
+    code: string;
+};
+/**
+ * Supported EVM chain names.
+ * Pass chain_name (preferred) or chain_id when calling EVM endpoints.
+ *
+ * Mainnets:  ethereum, polygon, arbitrum, base, optimism,
+ *            avalanche, bsc, linea, scroll, zksync
+ *
+ * Testnets:  sepolia, amoy, arbitrum-sepolia, base-sepolia,
+ *            optimism-sepolia, avalanche-fuji, bsc-testnet, zksync-sepolia
+ */
+type ChainName = "ethereum" | "polygon" | "arbitrum" | "base" | "optimism" | "avalanche" | "bsc" | "linea" | "scroll" | "zksync" | "sepolia" | "amoy" | "arbitrum-sepolia" | "base-sepolia" | "optimism-sepolia" | "avalanche-fuji" | "bsc-testnet" | "zksync-sepolia";
+/**
+ * Chain resolution params for EVM endpoints.
+ * Provide chainName (preferred) OR chainId — chainName takes precedence.
+ */
+type EVMChainParams = {
+    chainName: ChainName | string;
+    chainId?: never;
+} | {
+    chainId: string;
+    chainName?: never;
+};
+type ChainType = "evm" | "solana";
+type Chain = {
+    name: string;
+    chainId: string;
+    nativeSymbol: string;
+    legacySymbol?: string;
+    testnet: boolean;
+};
+type Wallet = {
+    id: string;
+    userId: string;
+    chainType: ChainType;
+    address: string;
+    label?: string;
+    createdAt: string;
+};
+type CreateWalletParams = {
+    userId: string;
+    chainType: ChainType;
+    /** Optional human-readable label for this wallet. */
+    label?: string;
+};
+type ListWalletsResult = {
+    wallets: Wallet[];
+    nextCursor: string | null;
+    hasMore: boolean;
+};
+type PaginationParams = {
+    /** Cursor from the previous page's nextCursor for pagination. */
+    after?: string;
+    limit?: number;
+};
+type SigningJob = {
+    jobId: string;
+    status: "pending" | "processing" | "completed" | "failed";
+};
+type SignEVMMessageParams = {
+    /** Raw message or typed data payload to sign. */
+    payload: Record<string, unknown>;
+    /** Optional deduplication key — safe to retry with the same key. */
+    idempotencyKey?: string;
+};
+type SignSolanaMessageParams = {
+    payload: Record<string, unknown>;
+    idempotencyKey?: string;
+};
+type EVMBalanceResult = {
+    address: string;
+    balance: string;
+    rawBalance: string;
+    symbol: string;
+    chainName: string;
+    chainId: string;
+};
+type SolanaBalanceResult = {
+    address: string;
+    balance: string;
+    rawBalance: string;
+    symbol: "SOL";
+};
+type BroadcastEVMResult = {
+    txHash: string;
+    chainName: string;
+    chainId: string;
+};
+type BroadcastSolanaResult = {
+    signature: string;
+};
+type SweepParams = {
+    chainType: ChainType;
+    /**
+     * EVM only — the chain to sweep from.
+     * chainName takes precedence over chainId.
+     */
+    chainName?: string;
+    chainId?: string;
+};
+type StablecoinToken = "usdc" | "usdt";
+type TransferSpeed = "slow" | "normal" | "fast";
+type StablecoinTransferParams = {
+    token: StablecoinToken;
+    /** Recipient wallet address. */
+    to: string;
+    /** Human-readable amount, e.g. "50.00". */
+    amount: string;
+    chainType: ChainType;
+    /** EVM only — chainName (preferred) or chainId. */
+    chainName?: string;
+    chainId?: string;
+    /** If true, the relayer pays gas on behalf of the sender. */
+    gasless?: boolean;
+    /** Controls transaction priority. Defaults to "normal". */
+    speed?: TransferSpeed;
+    /** Optional deduplication key. */
+    idempotencyKey?: string;
+};
+type StablecoinTransferResult = {
+    jobId: string;
+    status: string;
+};
+type StablecoinBalanceParams = {
+    token: StablecoinToken;
+    chainType: ChainType;
+    /** EVM only — chainName (preferred) or chainId. */
+    chainName?: string;
+    chainId?: string;
+};
+type StablecoinBalanceResult = {
+    address: string;
+    token: string;
+    symbol: string;
+    balance: string;
+    rawBalance: string;
+    chainId?: string;
+};
+type Job = {
+    id: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    operation: string;
+    result?: unknown;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+/**
+ * Signing operations — sign EVM and Solana messages.
+ *
+ * All signing operations are asynchronous. They return a job ID
+ * which you can poll via `vaultkey.jobs.get(jobId)` until the
+ * status is "completed" or "failed".
+ *
+ * Access via: `vaultkey.wallets.signing`
+ */
+declare class Signing {
+    private readonly client;
+    private readonly walletId;
+    constructor(client: VaultKey, walletId: string);
+    /**
+     * Sign an EVM message or typed data (EIP-712).
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.signing("wallet_id").evmMessage({
+     *   payload: { message: "Hello from VaultKey" },
+     * });
+     * // Poll: await vaultkey.jobs.get(data.jobId)
+     */
+    evmMessage(params: SignEVMMessageParams): Promise<VaultKeyResponse<SigningJob>>;
+    /**
+     * Sign a Solana message.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.signing("wallet_id").solanaMessage({
+     *   payload: { message: "Hello from VaultKey" },
+     * });
+     */
+    solanaMessage(params: SignSolanaMessageParams): Promise<VaultKeyResponse<SigningJob>>;
+}
+
+/**
+ * Wallet management — create wallets, retrieve them, sign messages,
+ * check balances, broadcast transactions, and trigger sweeps.
+ *
+ * @example
+ * const vaultkey = new VaultKey({ apiKey: "vk_live_...", apiSecret: "..." });
+ *
+ * // Create a wallet
+ * const { data } = await vaultkey.wallets.create({
+ *   userId: "user_123",
+ *   chainType: "evm",
+ * });
+ *
+ * // Sign a message
+ * const { data: job } = await vaultkey.wallets
+ *   .signing("wallet_id")
+ *   .evmMessage({ payload: { message: "Hello" } });
+ *
+ * // Poll until done
+ * const { data: result } = await vaultkey.jobs.get(job.jobId);
+ */
+declare class Wallets {
+    private readonly client;
+    constructor(client: VaultKey);
+    /**
+     * Create a new wallet for a user.
+     *
+     * @example
+     * const { data, error } = await vaultkey.wallets.create({
+     *   userId: "user_123",
+     *   chainType: "evm",
+     *   label: "Primary wallet",
+     * });
+     */
+    create(params: CreateWalletParams): Promise<VaultKeyResponse<Wallet>>;
+    /**
+     * Retrieve a wallet by its ID.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.get("wallet_abc123");
+     */
+    get(walletId: string): Promise<VaultKeyResponse<Wallet>>;
+    /**
+     * List all wallets belonging to a user.
+     * Results are paginated — use `nextCursor` to fetch the next page.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.listByUser("user_123");
+     * // Next page:
+     * const { data: page2 } = await vaultkey.wallets.listByUser("user_123", {
+     *   after: data.nextCursor,
+     * });
+     */
+    listByUser(userId: string, pagination?: PaginationParams): Promise<VaultKeyResponse<ListWalletsResult>>;
+    /**
+     * Returns a signing interface scoped to the given wallet.
+     * Use this to sign EVM or Solana messages.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets
+     *   .signing("wallet_id")
+     *   .evmMessage({ payload: { message: "Hello" } });
+     */
+    signing(walletId: string): Signing;
+    /**
+     * Get the native token balance for an EVM wallet.
+     * Provide chainName (preferred) or chainId.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.evmBalance("wallet_id", {
+     *   chainName: "base",
+     * });
+     * console.log(data.balance); // "0.05"
+     */
+    evmBalance(walletId: string, chain: EVMChainParams): Promise<VaultKeyResponse<EVMBalanceResult>>;
+    /**
+     * Get the SOL balance for a Solana wallet.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.solanaBalance("wallet_id");
+     * console.log(data.balance); // "1.5"
+     */
+    solanaBalance(walletId: string): Promise<VaultKeyResponse<SolanaBalanceResult>>;
+    /**
+     * Broadcast a pre-signed EVM transaction.
+     * Provide chainName (preferred) or chainId.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.broadcastEVM("wallet_id", {
+     *   signedTx: "0x...",
+     *   chainName: "base",
+     * });
+     * console.log(data.txHash);
+     */
+    broadcastEVM(walletId: string, params: {
+        signedTx: string;
+    } & EVMChainParams): Promise<VaultKeyResponse<BroadcastEVMResult>>;
+    /**
+     * Broadcast a pre-signed Solana transaction.
+     *
+     * @example
+     * const { data } = await vaultkey.wallets.broadcastSolana("wallet_id", {
+     *   signedTx: "base58encodedtx...",
+     * });
+     * console.log(data.signature);
+     */
+    broadcastSolana(walletId: string, params: {
+        signedTx: string;
+    }): Promise<VaultKeyResponse<BroadcastSolanaResult>>;
+    /**
+     * Trigger a sweep — move all funds from this wallet to the configured
+     * master wallet. The operation is asynchronous; poll via `vaultkey.jobs.get`.
+     *
+     * @example
+     * // EVM sweep
+     * const { data } = await vaultkey.wallets.sweep("wallet_id", {
+     *   chainType: "evm",
+     *   chainName: "base",
+     * });
+     *
+     * // Solana sweep
+     * const { data } = await vaultkey.wallets.sweep("wallet_id", {
+     *   chainType: "solana",
+     * });
+     */
+    sweep(walletId: string, params: SweepParams): Promise<VaultKeyResponse<SigningJob>>;
+}
+
+/**
+ * Job polling — check the status of async operations like signing and sweeps.
+ *
+ * Most VaultKey operations that involve on-chain activity are asynchronous.
+ * They return a `jobId` which you poll here until `status` is
+ * "completed" or "failed".
+ *
+ * @example
+ * const { data: job } = await vaultkey.wallets
+ *   .signing("wallet_id")
+ *   .evmMessage({ payload: { message: "Hello" } });
+ *
+ * // Poll until done
+ * let result;
+ * do {
+ *   await new Promise(r => setTimeout(r, 1000));
+ *   result = await vaultkey.jobs.get(job.jobId);
+ * } while (result.data?.status === "pending" || result.data?.status === "processing");
+ */
+declare class Jobs {
+    private readonly client;
+    constructor(client: VaultKey);
+    /**
+     * Retrieve the current state of an async job.
+     *
+     * @example
+     * const { data, error } = await vaultkey.jobs.get("job_abc123");
+     * if (data?.status === "completed") {
+     *   console.log("Done!", data.result);
+     * }
+     */
+    get(jobId: string): Promise<VaultKeyResponse<Job>>;
+}
+
+/**
+ * Stablecoin operations — transfer USDC/USDT and check stablecoin balances
+ * across EVM chains and Solana.
+ *
+ * @example
+ * const vaultkey = new VaultKey({ apiKey: "vk_live_...", apiSecret: "..." });
+ *
+ * // Transfer USDC on Base
+ * const { data } = await vaultkey.stablecoin.transfer("wallet_id", {
+ *   token: "usdc",
+ *   to: "0xRecipient",
+ *   amount: "50.00",
+ *   chainType: "evm",
+ *   chainName: "base",
+ *   gasless: true,
+ * });
+ *
+ * // Check USDC balance on Polygon
+ * const { data: bal } = await vaultkey.stablecoin.balance("wallet_id", {
+ *   token: "usdc",
+ *   chainType: "evm",
+ *   chainName: "polygon",
+ * });
+ */
+declare class Stablecoin {
+    private readonly client;
+    constructor(client: VaultKey);
+    /**
+     * Transfer a stablecoin from a wallet.
+     *
+     * - For EVM: provide chainName (preferred) or chainId.
+     * - For Solana: omit chainName and chainId.
+     * - The operation is async — poll `vaultkey.jobs.get(data.jobId)`.
+     * - Use `idempotencyKey` to safely retry without double-sending.
+     *
+     * @example
+     * // EVM (gasless)
+     * const { data } = await vaultkey.stablecoin.transfer("wallet_id", {
+     *   token: "usdc",
+     *   to: "0xRecipient",
+     *   amount: "100.00",
+     *   chainType: "evm",
+     *   chainName: "base",
+     *   gasless: true,
+     *   speed: "fast",
+     * });
+     *
+     * // Solana
+     * const { data } = await vaultkey.stablecoin.transfer("wallet_id", {
+     *   token: "usdc",
+     *   to: "RecipientBase58",
+     *   amount: "100.00",
+     *   chainType: "solana",
+     * });
+     */
+    transfer(walletId: string, params: StablecoinTransferParams): Promise<VaultKeyResponse<StablecoinTransferResult>>;
+    /**
+     * Get the stablecoin balance for a wallet.
+     *
+     * - For EVM: provide chainName (preferred) or chainId.
+     * - For Solana: omit chainName and chainId.
+     *
+     * @example
+     * const { data } = await vaultkey.stablecoin.balance("wallet_id", {
+     *   token: "usdc",
+     *   chainType: "evm",
+     *   chainName: "polygon",
+     * });
+     * console.log(data.balance); // "50.00"
+     */
+    balance(walletId: string, params: StablecoinBalanceParams): Promise<VaultKeyResponse<StablecoinBalanceResult>>;
+}
+
+/**
+ * Chain discovery — list supported chains for the current environment.
+ *
+ * Use this to build chain selectors in your UI or to validate
+ * chain names before passing them to other SDK methods.
+ *
+ * @example
+ * const { data } = await vaultkey.chains.list();
+ * // [{ name: "base", chainId: "8453", nativeSymbol: "ETH", testnet: false }, ...]
+ */
+declare class Chains {
+    private readonly client;
+    constructor(client: VaultKey);
+    /**
+     * List all supported EVM chains for the current environment
+     * (testnet or mainnet, determined by your API key).
+     *
+     * @example
+     * const { data, error } = await vaultkey.chains.list();
+     */
+    list(): Promise<VaultKeyResponse<Chain[]>>;
+}
+
+type RequestOptions = {
+    headers?: HeadersInit;
+};
+interface VaultKeyConfig {
+    /**
+     * Your VaultKey API key.
+     * Testnet keys start with `testnet_`, live keys start with `vk_live_`.
+     * Falls back to the VAULTKEY_API_KEY environment variable.
+     *
+     * The SDK automatically routes requests to the correct endpoint:
+     * - `testnet_` → https://testnet.vaultkeys.dev
+     * - `vk_live_` → https://app.vaultkeys.dev
+     */
+    apiKey?: string;
+    /**
+     * Your VaultKey API secret.
+     * Falls back to the VAULTKEY_API_SECRET environment variable.
+     */
+    apiSecret?: string;
+    /**
+     * Override the base URL. Useful for self-hosted deployments or proxies.
+     * When set, this takes precedence over the automatic key-based routing.
+     */
+    baseUrl?: string;
+}
+declare class VaultKey {
+    private readonly apiKey;
+    private readonly apiSecret;
+    readonly baseUrl: string;
+    /** Wallet management — create, retrieve, and list wallets. */
+    readonly wallets: Wallets;
+    /** Async job polling — check the status of signing and sweep operations. */
+    readonly jobs: Jobs;
+    /** Stablecoin transfers and balance lookups (USDC, USDT). */
+    readonly stablecoin: Stablecoin;
+    /** Chain discovery — list supported EVM chains for the current environment. */
+    readonly chains: Chains;
+    constructor(config?: VaultKeyConfig);
+    fetchRequest<T>(path: string, options?: RequestInit): Promise<{
+        data: T | null;
+        error: ErrorResponse | null;
+    }>;
+    get<T>(path: string, options?: RequestOptions): Promise<{
+        data: T | null;
+        error: ErrorResponse | null;
+    }>;
+    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<{
+        data: T | null;
+        error: ErrorResponse | null;
+    }>;
+    put<T>(path: string, body: unknown, options?: RequestOptions): Promise<{
+        data: T | null;
+        error: ErrorResponse | null;
+    }>;
+    patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<{
+        data: T | null;
+        error: ErrorResponse | null;
+    }>;
+    delete<T>(path: string, body?: unknown, options?: RequestOptions): Promise<{
+        data: T | null;
+        error: ErrorResponse | null;
+    }>;
+}
+
+export { type BroadcastEVMResult, type BroadcastSolanaResult, type Chain, type ChainName, type ChainType, Chains, type CreateWalletParams, type EVMBalanceResult, type EVMChainParams, type ErrorResponse, type Job, Jobs, type ListWalletsResult, type PaginationParams, type SignEVMMessageParams, type SignSolanaMessageParams, Signing, type SigningJob, type SolanaBalanceResult, Stablecoin, type StablecoinBalanceParams, type StablecoinBalanceResult, type StablecoinToken, type StablecoinTransferParams, type StablecoinTransferResult, type SweepParams, type TransferSpeed, VaultKey, type VaultKeyConfig, type VaultKeyResponse, type Wallet, Wallets };