@openpump/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,473 @@
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+}
+declare class HttpClient {
+    private readonly _apiKey;
+    private readonly _baseUrl;
+    private readonly _timeout;
+    constructor(config: HttpClientConfig);
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    private _headers;
+    private _handleResponse;
+    private _throwApiError;
+}
+
+interface CreateWalletOptions {
+    label?: string;
+}
+interface WalletInfo {
+    id: string;
+    publicKey: string;
+    walletIndex: number;
+    label: string;
+    createdAt: string;
+}
+interface WalletBalance {
+    nativeSol: {
+        lamports: string;
+        sol: string;
+    };
+    tokens: Array<{
+        mint: string;
+        symbol: string | null;
+        amount: string;
+        decimals: number;
+        uiAmount: number;
+    }>;
+}
+interface DepositInstructions {
+    depositAddress: string;
+    minimums: {
+        tokenCreation: string;
+        bundleBuy: string;
+        standardBuy: string;
+    };
+    instructions: string[];
+    disclaimer: string;
+    network: string;
+}
+interface TransferOptions {
+    toAddress: string;
+    amountLamports: string;
+    mint?: string | null;
+    memo?: string;
+    priorityFeeMicroLamports?: number;
+}
+interface TransferResult {
+    signature: string;
+    amountLamports: string;
+    fee: string;
+}
+interface TransactionListOptions {
+    type?: 'buy' | 'sell' | 'transfer';
+    limit?: number;
+    offset?: number;
+}
+interface TransactionListResult {
+    transactions: Array<Record<string, unknown>>;
+    total: number;
+    limit: number;
+    offset: number;
+}
+declare class Wallets {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /** List all active wallets for the authenticated user. */
+    list(): Promise<WalletInfo[]>;
+    /** Create a new wallet with an optional label. */
+    create(options?: CreateWalletOptions): Promise<WalletInfo>;
+    /** Get a single wallet by ID. */
+    get(walletId: string): Promise<WalletInfo>;
+    /** Get SOL + token balances for a wallet. */
+    getBalance(walletId: string): Promise<WalletBalance>;
+    /** Get deposit address and SOL minimums for a wallet. */
+    getDepositInstructions(walletId: string): Promise<DepositInstructions>;
+    /** Force a live RPC balance refresh, bypassing the 30s cache. */
+    refreshBalance(walletId: string): Promise<WalletBalance>;
+    /**
+     * Execute an on-chain SOL or SPL token transfer.
+     *
+     * @example
+     * ```ts
+     * const result = await op.wallets.transfer('wallet-id', {
+     *   toAddress: 'recipient-public-key',
+     *   amountLamports: '100000000',
+     * });
+     * console.log(result.signature);
+     * ```
+     */
+    transfer(walletId: string, options: TransferOptions): Promise<TransferResult>;
+    /** Get paginated transfer history for a wallet. */
+    getTransactions(walletId: string, options?: TransactionListOptions): Promise<TransactionListResult>;
+}
+
+interface CreateTokenOptions {
+    walletIndex?: number;
+    name: string;
+    symbol: string;
+    description: string;
+    imageBase64: string;
+    imageType: 'image/png' | 'image/jpeg' | 'image/jpg' | 'image/gif' | 'image/webp';
+    initialBuyAmountSol?: number;
+    twitter?: string;
+    telegram?: string;
+    website?: string;
+}
+interface CreateTokenResult {
+    tokenId: string;
+    mint: string;
+    signature: string;
+    metadataUri: string;
+    bondingCurveAccount: string;
+}
+interface TokenListItem {
+    id: string;
+    mintAddress: string;
+    name: string;
+    symbol: string;
+    graduationStatus: string;
+    metadataUri: string;
+    creatorAddress: string;
+    createdAt: string;
+}
+interface CurveState {
+    mint: string;
+    virtualTokenReserves: string;
+    virtualSolReserves: string;
+    realTokenReserves: string;
+    realSolReserves: string;
+    tokenTotalSupply: string;
+    complete: boolean;
+    isMayhemMode: boolean;
+    currentPriceSOL: number;
+    marketCapSOL: number;
+    graduationPercent: number;
+}
+declare class Tokens {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /** List tokens created by the authenticated user. */
+    list(): Promise<TokenListItem[]>;
+    /**
+     * Create a new PumpFun token with IPFS metadata upload.
+     *
+     * @example
+     * ```ts
+     * const token = await op.tokens.create({
+     *   name: 'My Token',
+     *   symbol: 'MTK',
+     *   description: 'A cool token',
+     *   imageBase64: 'base64-encoded-image...',
+     *   imageType: 'image/png',
+     * });
+     * console.log(token.mint);
+     * ```
+     */
+    create(options: CreateTokenOptions): Promise<CreateTokenResult>;
+    /** Get market info for a token (mainnet only, returns null on devnet). */
+    getMarketInfo(mint: string): Promise<Record<string, unknown> | null>;
+    /** Get bonding curve state including price, market cap, and graduation progress. */
+    getCurveState(mint: string): Promise<CurveState>;
+}
+
+type PriorityLevel = 'economy' | 'normal' | 'fast' | 'turbo';
+interface QuoteOptions {
+    action: 'buy' | 'sell';
+    solAmount?: string;
+    tokenAmount?: string;
+}
+interface QuoteResult {
+    route: 'bonding_curve' | 'pumpswap';
+    expectedTokens?: string;
+    expectedSol?: string;
+    priceImpact: number;
+    fee: number;
+    disclaimer: string;
+}
+interface QuoteBuyCostOptions {
+    tokenAmount: string;
+}
+interface QuoteBuyCostResult {
+    solCostLamports: string;
+    route: 'bonding_curve' | 'pumpswap';
+    disclaimer: string;
+}
+interface BuyOptions {
+    walletId: string;
+    amountLamports: string;
+    slippageBps?: number;
+    priorityLevel?: PriorityLevel;
+}
+interface BuyResult {
+    signature: string;
+    estimatedTokenAmount: string;
+    solSpent: string;
+    route: 'bonding_curve' | 'pumpswap';
+    disclaimer: string;
+}
+interface SellOptions {
+    walletId: string;
+    tokenAmount: string;
+    slippageBps?: number;
+    priorityLevel?: PriorityLevel;
+}
+interface SellResult {
+    signature: string;
+    estimatedSolReceived: string;
+    tokensSold: string;
+    route: 'bonding_curve' | 'pumpswap';
+    disclaimer: string;
+}
+interface BundleSellEntry {
+    walletId: string;
+    tokenAmount: string;
+}
+interface BundleSellOptions {
+    walletSells: BundleSellEntry[];
+    tipWalletId?: string;
+    tipLamports?: number;
+    slippageBps?: number;
+    priorityLevel?: PriorityLevel;
+}
+interface BundleSellResult {
+    bundleResults: Array<{
+        bundleId: string;
+        status: 'Landed' | 'Failed' | 'Timeout';
+        signatures?: string[];
+        walletsIncluded: string[];
+    }>;
+    warnings: Array<{
+        walletId: string;
+        reason: string;
+    }>;
+}
+declare class Trading {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /**
+     * Get a price quote for buying or selling a token.
+     *
+     * @example
+     * ```ts
+     * const quote = await op.trading.getQuote('So11...', {
+     *   action: 'buy',
+     *   solAmount: '1000000000',
+     * });
+     * console.log(quote.expectedTokens);
+     * ```
+     */
+    getQuote(mint: string, options: QuoteOptions): Promise<QuoteResult>;
+    /** Get the SOL cost to buy a specific number of tokens (inverse quote). */
+    getQuoteBuyCost(mint: string, options: QuoteBuyCostOptions): Promise<QuoteBuyCostResult>;
+    /** Execute a buy transaction for a token. */
+    buy(mint: string, options: BuyOptions): Promise<BuyResult>;
+    /** Execute a sell transaction for a token. */
+    sell(mint: string, options: SellOptions): Promise<SellResult>;
+    /** Multi-wallet sell packed into Jito bundles. */
+    bundleSell(mint: string, options: BundleSellOptions): Promise<BundleSellResult>;
+}
+
+interface JobStatus {
+    jobId: string;
+    status: 'waiting' | 'active' | 'completed' | 'failed';
+    progress: number;
+    result?: {
+        bundleStatuses: Array<{
+            bundleId: string;
+            status: 'Pending' | 'Landed' | 'Failed' | 'Timeout';
+            signatures?: string[];
+        }>;
+    };
+    warnings?: Array<{
+        walletId: string;
+        reason: string;
+    }>;
+    error?: string;
+}
+interface PollOptions {
+    /** Polling interval in milliseconds. Default: 1000 */
+    intervalMs?: number;
+    /** Maximum time to wait in milliseconds. Default: 30000 */
+    timeoutMs?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+    /** Callback invoked on each poll with current status. */
+    onProgress?: (status: JobStatus) => void;
+}
+declare class Jobs {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /** Get the current status of a job. */
+    get(jobId: string): Promise<JobStatus>;
+    /**
+     * Poll a job until it completes or the timeout is reached.
+     *
+     * @param jobId - The job ID to poll.
+     * @param options - Polling configuration.
+     * @returns The final job status (completed).
+     * @throws {Error} If the job fails or the timeout is reached.
+     *
+     * @example
+     * ```ts
+     * const launch = await op.bundles.launch({ ... });
+     * const result = await op.jobs.poll(launch.jobId, {
+     *   intervalMs: 2000,
+     *   timeoutMs: 60000,
+     *   onProgress: (s) => console.log(`Progress: ${s.progress}%`),
+     * });
+     * ```
+     */
+    poll(jobId: string, options?: PollOptions): Promise<JobStatus>;
+}
+
+interface AccumulatedFees {
+    creatorAddress: string;
+    accumulatedLamports: string;
+    accumulatedSOL: number;
+    creatorVaultAddress: string;
+}
+interface ClaimFeesResult {
+    signature: string;
+    amountClaimed: string;
+    amountClaimedSOL: number;
+}
+declare class CreatorFees {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /** Get accumulated creator fees for a given creator address. */
+    getAccumulatedFees(address: string): Promise<AccumulatedFees>;
+    /** Claim accumulated creator fees for a wallet you own. */
+    claim(creatorAddress: string): Promise<ClaimFeesResult>;
+}
+
+interface BundleLaunchOptions {
+    devWalletId: string;
+    buyWalletIds: string[];
+    name: string;
+    symbol: string;
+    description?: string;
+    imageBase64: string;
+    imageType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    devBuyAmountLamports?: string;
+    walletBuyAmounts: string[];
+    tipLamports?: number;
+    twitter?: string;
+    telegram?: string;
+    website?: string;
+}
+interface BundleLaunchResult {
+    jobId: string;
+}
+declare class Bundles {
+    private readonly _http;
+    constructor(_http: HttpClient);
+    /**
+     * Launch a coordinated token creation + multi-wallet bundle buy.
+     * Returns a job ID for polling.
+     *
+     * @example
+     * ```ts
+     * const { jobId } = await op.bundles.launch({
+     *   devWalletId: 'wallet-1',
+     *   buyWalletIds: ['wallet-2', 'wallet-3'],
+     *   name: 'My Token',
+     *   symbol: 'MTK',
+     *   imageBase64: '...',
+     *   imageType: 'image/png',
+     *   walletBuyAmounts: ['500000000', '500000000'],
+     * });
+     * const result = await op.jobs.poll(jobId);
+     * ```
+     */
+    launch(options: BundleLaunchOptions): Promise<BundleLaunchResult>;
+}
+
+interface OpenPumpConfig {
+    /** API key (op_sk_live_...) */
+    apiKey: string;
+    /** Base URL of the OpenPump API. Defaults to https://api.openpump.io */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30_000 */
+    timeout?: number;
+}
+/**
+ * OpenPump SDK client with resource-namespaced API methods.
+ *
+ * @example
+ * ```ts
+ * import { OpenPump } from '@openpump/sdk';
+ *
+ * const op = new OpenPump({ apiKey: 'op_sk_live_...' });
+ *
+ * // List wallets
+ * const wallets = await op.wallets.list();
+ *
+ * // Create a token
+ * const token = await op.tokens.create({ ... });
+ *
+ * // Buy tokens
+ * const trade = await op.trading.buy('mint-address', { ... });
+ *
+ * // Poll a bundle launch job
+ * const job = await op.jobs.poll('job-id', { timeoutMs: 60_000 });
+ * ```
+ */
+declare class OpenPump {
+    readonly wallets: Wallets;
+    readonly tokens: Tokens;
+    readonly trading: Trading;
+    readonly jobs: Jobs;
+    readonly creatorFees: CreatorFees;
+    readonly bundles: Bundles;
+    private readonly _http;
+    constructor(config: OpenPumpConfig);
+}
+
+/**
+ * Base error class for all OpenPump SDK errors.
+ * All API errors are converted to typed exceptions.
+ */
+declare class OpenPumpError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    readonly name: string;
+    constructor(code: string, message: string, status: number, details?: unknown | undefined);
+}
+/** Thrown when the API key is invalid or missing (HTTP 401). */
+declare class AuthenticationError extends OpenPumpError {
+    readonly name = "AuthenticationError";
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+/** Thrown when the rate limit is exceeded (HTTP 429). */
+declare class RateLimitError extends OpenPumpError {
+    readonly name = "RateLimitError";
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+/** Thrown when request validation fails (HTTP 422). */
+declare class ValidationError extends OpenPumpError {
+    readonly name = "ValidationError";
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+/** Thrown when the requested resource is not found (HTTP 404). */
+declare class NotFoundError extends OpenPumpError {
+    readonly name = "NotFoundError";
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+/** Thrown when the wallet has insufficient SOL or tokens for an operation. */
+declare class InsufficientFundsError extends OpenPumpError {
+    readonly name = "InsufficientFundsError";
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+/** Thrown when an on-chain transaction fails (signature error, simulation failure, etc.). */
+declare class TransactionError extends OpenPumpError {
+    readonly name = "TransactionError";
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+
+export { type AccumulatedFees, AuthenticationError, type BundleLaunchOptions, type BundleLaunchResult, type BundleSellEntry, type BundleSellOptions, type BundleSellResult, Bundles, type BuyOptions, type BuyResult, type ClaimFeesResult, type CreateTokenOptions, type CreateTokenResult, type CreateWalletOptions, CreatorFees, type CurveState, type DepositInstructions, InsufficientFundsError, type JobStatus, Jobs, NotFoundError, OpenPump, type OpenPumpConfig, OpenPumpError, type PollOptions, type PriorityLevel, type QuoteBuyCostOptions, type QuoteBuyCostResult, type QuoteOptions, type QuoteResult, RateLimitError, type SellOptions, type SellResult, type TokenListItem, Tokens, Trading, TransactionError, type TransactionListOptions, type TransactionListResult, type TransferOptions, type TransferResult, ValidationError, type WalletBalance, type WalletInfo, Wallets };