@gramio/crypto-pay-api/dist/index.d.ts

CryptoPay / CryptoBot API client

type Network = "mainnet" | "testnet";
/**
 * List of supported cryptocurrency assets available in Crypto Pay.
 *
 * @see https://help.crypt.bot/crypto-pay-api#assets
 */
type Asset = "USDT" | "TON" | "BTC" | "ETH" | "LTC" | "BNB" | "TRX" | "USDC" | "JET";
/**
 * List of supported fiat currency codes accepted by Crypto Pay.
 *
 * @see https://help.crypt.bot/crypto-pay-api#currencies
 */
type FiatCurrency = "USD" | "EUR" | "RUB" | "BYN" | "UAH" | "GBP" | "CNY" | "KZT" | "UZS" | "GEL" | "TRY" | "AMD" | "THB" | "INR" | "BRL" | "IDR" | "AZN" | "AED" | "PLN" | "ILS";
/**
 * Identifies whether an invoice amount is specified in cryptocurrency or fiat.
 */
type CurrencyType = "crypto" | "fiat";
/**
 * Possible lifecycle states of an invoice.
 */
type InvoiceStatus = "active" | "paid" | "expired";
/**
 * Possible lifecycle states of a check.
 */
type CheckStatus = "active" | "activated";
/**
 * The only status a transfer can have once completed.
 */
type TransferStatus = "completed";
/**
 * Preset button names displayed to the user after a successful payment.
 */
type PaidButtonName = "viewItem" | "openChannel" | "openBot" | "callback";
/**
 * Full representation of an invoice returned by Crypto Pay API.
 */
interface Invoice {
    /** Unique identifier of the invoice. */
    invoice_id: number;
    /** Current status of the invoice. */
    status: InvoiceStatus;
    /** Indicates whether the invoice amount is in crypto or fiat. */
    currency_type: CurrencyType;
    /** Crypto asset used when currency_type is "crypto". */
    asset?: Asset;
    /** Fiat currency code when currency_type is "fiat". */
    fiat?: FiatCurrency;
    /** Assets accepted for payment when amount is specified in fiat. */
    accepted_assets?: Asset[];
    /** Invoice amount represented as stringified float. */
    amount: string;
    /** Public hash of the invoice. */
    hash: string;
    /** Optional description visible to the payer. */
    description?: string;
    /** Deep-link URL to pay the invoice in Telegram bot. */
    bot_invoice_url?: string;
    /** Invoice URL for Telegram Mini Apps. */
    mini_app_invoice_url?: string;
    /** Invoice URL for Web Apps. */
    web_app_invoice_url?: string;
    /** Allows payer to change the amount. */
    is_flexible?: boolean;
    /** Asset used to pay the invoice. */
    paid_asset?: Asset;
    /** Amount actually paid. */
    paid_amount?: string;
    /** USD exchange rate of paid_asset at payment time. */
    paid_usd_rate?: string;
    /** Exchange rate of paid_asset to specified fiat currency. */
    paid_fiat_rate?: string;
    /** Asset in which service fee was charged. */
    fee_asset?: Asset;
    /** Charged service fee amount. */
    fee_amount?: string;
    /** Whether the payment was automatically swapped. */
    is_swapped?: boolean;
    /** Requested asset to swap to. */
    swap_to?: Asset;
    /** Internal swap transaction identifier. */
    swapped_uid?: number;
    /** Asset funds were swapped to. */
    swapped_to?: Asset;
    /** Exchange rate applied during swap. */
    swapped_rate?: string;
    /** Resulting amount after swap. */
    swapped_output?: string;
    /** USD rate of swapped_to asset at swap time. */
    swapped_usd_rate?: string;
    /** ISO-8601 creation timestamp. */
    created_at: string;
    /** True if payer can leave comments. */
    allow_comments: boolean;
    /** True if anonymous payments are allowed. */
    allow_anonymous: boolean;
    /** ISO-8601 expiration timestamp, if set. */
    expiration_date?: string;
    /** ISO-8601 timestamp when payment was received. */
    paid_at?: string;
    /** Indicates that payment was made anonymously. */
    paid_anonymously?: boolean;
    /** Comment left by the payer. */
    comment?: string;
    /** Hidden message displayed after payment. */
    hidden_message?: string;
    /** Custom payload attached to the invoice. */
    payload?: string;
    /** Post-payment button label. */
    paid_btn_name?: PaidButtonName;
    /** URL opened by the post-payment button. */
    paid_btn_url?: string;
}
/**
 * Outgoing crypto transfer executed by the app.
 */
interface Transfer {
    /** Unique identifier of the transfer. */
    transfer_id: number;
    /** Unique spend identifier provided when creating the transfer. */
    spend_id?: string;
    /** Telegram user ID that received the transfer. */
    user_id: string;
    /** Crypto asset that was transferred. */
    asset: Asset;
    /** Amount transferred represented as stringified float. */
    amount: string;
    /** Transfer status (always "completed"). */
    status: TransferStatus;
    /** ISO-8601 timestamp when the transfer was completed. */
    completed_at: string;
    /** Optional comment attached to the transfer. */
    comment?: string;
}
/**
 * Crypto check (voucher) that users can redeem.
 */
interface Check {
    /** Unique identifier of the check. */
    check_id: number;
    /** Public hash of the check used for activation. */
    hash: string;
    /** Crypto asset stored in the check. */
    asset: Asset;
    /** Amount stored in the check represented as stringified float. */
    amount: string;
    /** URL that should be provided to a user to activate the check. */
    bot_check_url: string;
    /** Current status of the check. */
    status: CheckStatus;
    /** ISO-8601 creation timestamp. */
    created_at: string;
    /** ISO-8601 activation timestamp, if the check has been redeemed. */
    activated_at?: string;
}
/**
 * Balance information for a specific crypto asset.
 */
interface Balance {
    /** Crypto asset code. */
    currency_code: Asset;
    /** Total available balance represented as stringified float. */
    available: string;
    /** Amount currently on hold represented as stringified float. */
    onhold: string;
}
/**
 * Exchange rate between a crypto asset and a fiat currency.
 */
interface ExchangeRate {
    /** True if the rate is up-to-date. */
    is_valid: boolean;
    /** True if the source is a cryptocurrency. */
    is_crypto: boolean;
    /** True if the source is a fiat currency. */
    is_fiat: boolean;
    /** Crypto asset code. */
    source: Asset;
    /** Fiat currency code. */
    target: FiatCurrency;
    /** Current exchange rate represented as stringified float. */
    rate: string;
}
/**
 * Aggregated statistics calculated by Crypto Pay.
 */
interface AppStats {
    /** Total volume of paid invoices in USD. */
    volume: number;
    /** Conversion rate of all created invoices. */
    conversion: number;
    /** Unique number of users who have paid invoices. */
    unique_users_count: number;
    /** Total number of created invoices. */
    created_invoice_count: number;
    /** Total number of paid invoices. */
    paid_invoice_count: number;
    /** ISO-8601 timestamp marking the start of the calculation period. */
    start_at: string;
    /** ISO-8601 timestamp marking the end of the calculation period. */
    end_at: string;
}
/**
 * Union of possible webhook update types.
 */
type WebhookUpdateType = "invoice_paid";
/**
 * Webhook payload delivered by Crypto Pay.
 */
interface WebhookUpdate {
    /** Non-unique update identifier. */
    update_id: number;
    /** Type of the update (currently only "invoice_paid"). */
    update_type: WebhookUpdateType;
    /** ISO-8601 timestamp when the request was sent. */
    request_date: string;
    /** Invoice payload associated with the update. */
    payload: Invoice;
}
/**
 * Successful API response wrapper.
 */
interface ApiSuccess<T> {
    /** Indicates success. Always true. */
    ok: true;
    /** Result of the successful API call. */
    result: T;
}
/**
 * Error API response wrapper.
 */
interface ApiError {
    /** Indicates failure. Always false. */
    ok: false;
    /** Error code or message returned by the API. */
    error: {
        code: number;
        name: string;
    };
}
/**
 * Generic API response union.
 */
type ApiResponse<T> = ApiSuccess<T> | ApiError;
/**
 * Parameters accepted by the createInvoice method.
 */
interface CreateInvoiceParams {
    currency_type?: CurrencyType;
    asset?: Asset;
    fiat?: FiatCurrency;
    accepted_assets?: Asset[];
    amount: string;
    description?: string;
    hidden_message?: string;
    paid_btn_name?: PaidButtonName;
    paid_btn_url?: string;
    payload?: string;
    allow_comments?: boolean;
    allow_anonymous?: boolean;
    expires_in?: number;
    is_flexible?: boolean;
    swap_to?: Asset;
}
/**
 * Parameters accepted by the deleteInvoice method.
 */
interface DeleteInvoiceParams {
    invoice_ids: number[];
}
/**
 * Parameters required to create a check.
 */
interface CreateCheckParams {
    asset: Asset;
    amount: string;
}
/**
 * Parameters used to delete checks.
 */
interface DeleteCheckParams {
    check_ids: number[];
}
/**
 * Parameters required to transfer funds to a Telegram user.
 */
interface TransferParams {
    user_id: string;
    asset: Asset;
    amount: string;
    spend_id?: string;
    comment?: string;
}
/**
 * Filtering options for getInvoices.
 */
interface GetInvoicesParams {
    invoice_ids?: number[];
    status?: InvoiceStatus;
    offset?: number;
    count?: number;
    from?: string;
    to?: string;
}
/**
 * Filtering options for getChecks.
 */
interface GetChecksParams {
    check_ids?: number[];
    status?: CheckStatus;
    offset?: number;
    count?: number;
    from?: string;
    to?: string;
}
/**
 * Filtering options for getTransfers.
 */
interface GetTransfersParams {
    transfer_ids?: number[];
    spend_id?: string;
    offset?: number;
    count?: number;
    from?: string;
    to?: string;
}
/**
 * Parameters for retrieving aggregated statistics.
 */
interface GetStatsParams {
    start_at: string;
    end_at?: string;
}
/**
 * Basic information about an app returned by getMe.
 */
interface AppInfo {
    /** Unique numeric identifier of the app. */
    app_id: number;
    /** Public name of the app. */
    name: string;
    /** Telegram bot username associated with the app. */
    bot_username: string;
}

declare const frameworks: {
    elysia: ({ body, headers }: any) => {
        body: any;
        response: () => Response;
        getSignatureHeader: () => any;
    };
    fastify: (request: any, reply: any) => {
        body: any;
        response: () => any;
        getSignatureHeader: () => any;
    };
    hono: (c: any) => {
        body: any;
        response: () => any;
        getSignatureHeader: () => any;
    };
    express: (req: any, res: any) => {
        body: any;
        response: () => any;
        getSignatureHeader: () => any;
    };
    koa: (ctx: any) => {
        body: any;
        response: () => void;
        getSignatureHeader: () => any;
    };
    http: (req: any, res: any) => {
        body: Promise<unknown>;
        response: () => any;
        getSignatureHeader: () => any;
    };
    "std/http": (req: any) => {
        body: any;
        response: () => Response;
        getSignatureHeader: () => any;
    };
    "Bun.serve": (req: any) => {
        body: any;
        response: () => Response;
        getSignatureHeader: () => any;
    };
};

declare function webhookHandler<Framework extends keyof typeof frameworks>(client: CryptoPayAPI, framework: Framework): ReturnType<(typeof frameworks)[Framework]> extends {
    response: () => any;
} ? (...args: Parameters<(typeof frameworks)[Framework]>) => ReturnType<ReturnType<(typeof frameworks)[Framework]>["response"]> : ReturnType<(typeof frameworks)[Framework]>["response"];

/**
 * CryptoPay API client.
 */
declare class CryptoPayAPI {
    private readonly apiKey;
    private readonly endpoint;
    private readonly listeners;
    /**
     * Creates a new CryptoPayAPI instance.
     * @param apiKey - The API key to use for authentication.
     * @param network - The network to use for the API.
     */
    constructor(apiKey: string, network?: Network);
    private request;
    emit(data: WebhookUpdate, signature: string): Promise<boolean>;
    on(_event: WebhookUpdateType, listener: (data: WebhookUpdate) => unknown): void;
    /**
     * Tests the authentication token and retrieves basic app information.
     * @returns {@link AppInfo} wrapped in {@link ApiResponse}.
     */
    getMe(): Promise<AppInfo>;
    /**
     * Creates a new invoice and returns the created invoice object.
     * @param params Parameters accepted by createInvoice method.
     */
    createInvoice(params: CreateInvoiceParams): Promise<Invoice>;
    /**
     * Deletes one or multiple invoices by ID.
     * @param params List of invoice IDs to delete.
     */
    deleteInvoice(params: DeleteInvoiceParams): Promise<Invoice[]>;
    /**
     * Creates a crypto check (voucher).
     * @param params Check creation parameters.
     */
    createCheck(params: CreateCheckParams): Promise<Check>;
    /**
     * Deletes existing checks by IDs.
     * @param params List of check IDs to delete.
     */
    deleteCheck(params: DeleteCheckParams): Promise<Check[]>;
    /**
     * Transfers funds from the app balance to a Telegram user.
     * @param params Transfer parameters including user ID and asset.
     */
    transfer(params: TransferParams): Promise<Transfer>;
    /**
     * Retrieves invoices optionally filtered by status, period or identifiers.
     * @param params Optional filtering parameters.
     */
    getInvoices(params?: GetInvoicesParams): Promise<Invoice[]>;
    /**
     * Retrieves checks optionally filtered by status or period.
     * @param params Optional filtering parameters.
     */
    getChecks(params?: GetChecksParams): Promise<Check[]>;
    /**
     * Retrieves transfers optionally filtered by identifiers or period.
     * @param params Optional filtering parameters.
     */
    getTransfers(params?: GetTransfersParams): Promise<Transfer[]>;
    /**
     * Retrieves current asset balances of the app wallet.
     */
    getBalance(): Promise<Balance[]>;
    /**
     * Retrieves current exchange rates for supported crypto assets.
     */
    getExchangeRates(): Promise<ExchangeRate[]>;
    /**
     * Retrieves list of currencies supported by the platform.
     */
    getCurrencies(): Promise<Asset[]>;
    /**
     * Retrieves aggregated application statistics for a specified period.
     * @param params Date range parameters.
     */
    getStats(params: GetStatsParams): Promise<AppStats>;
}

export { type ApiError, type ApiResponse, type ApiSuccess, type AppInfo, type AppStats, type Asset, type Balance, type Check, type CheckStatus, type CreateCheckParams, type CreateInvoiceParams, CryptoPayAPI, type CurrencyType, type DeleteCheckParams, type DeleteInvoiceParams, type ExchangeRate, type FiatCurrency, type GetChecksParams, type GetInvoicesParams, type GetStatsParams, type GetTransfersParams, type Invoice, type InvoiceStatus, type Network, type PaidButtonName, type Transfer, type TransferParams, type TransferStatus, type WebhookUpdate, type WebhookUpdateType, webhookHandler };