/**
 * Profile Types
 *
 * Types for user profile operations including fetching user profile data.
 */
import type { BaseAPI } from "../api";
import type { OrderSide, OrderStatus, OrderType, TimeInForce } from "../trading";
/**
 * Account movement/transaction information.
 * Represents transactions/movements returned in the profile's recent_movements array.
 */
export interface ProfileMovement {
    /** Movement identifier */
    id: string;
    /** Movement type */
    type: "deposit" | "withdrawal" | "trade" | "transfer" | string;
    /** Token address */
    token: string;
    /** Amount of the movement (as string to preserve precision) */
    amount: string;
    /** Movement timestamp (ISO string) */
    timestamp: string;
    /** Transaction hash if applicable */
    hash?: string;
    /** Movement status */
    status: "pending" | "confirmed" | "failed" | string;
    /** Optional description of the movement */
    description?: string;
}
/**
 * Ledger movement from the movement's endpoint.
 * More detailed than ProfileMovement with balance tracking.
 */
export interface LedgerMovement {
    /** Movement unique identifier */
    id: string;
    /** Type of entry (Credit, Debit) */
    entry_type: string;
    /** Type of transaction (Deposit, Withdrawal, Trade, etc.) */
    transaction_type: string;
    /** Transaction amount (normalized, human-readable) */
    amount: string;
    /** Transaction amount in raw format (wei) */
    amount_raw: string;
    /** Token contract address */
    token: string;
    /** Token symbol */
    symbol: string | null;
    /** Token decimals */
    decimals: number;
    /** Balance before this transaction (normalized) */
    balance_before: string | null;
    /** Balance before in raw format (wei) */
    balance_before_raw: string | null;
    /** Balance after this transaction (normalized) */
    balance_after: string | null;
    /** Balance after in raw format (wei) */
    balance_after_raw: string | null;
    /** Locked balance before transaction (normalized) */
    locked_before: string | null;
    /** Locked balance before in raw format (wei) */
    locked_before_raw: string | null;
    /** Locked balance after transaction (normalized) */
    locked_after: string | null;
    /** Locked balance after in raw format (wei) */
    locked_after_raw: string | null;
    /** Reference identifier for related operations */
    reference_id: string | null;
    /** Reference type */
    reference_type: string | null;
    /** Human readable description */
    description: string | null;
    /** Blockchain transaction hash */
    tx_hash: string | null;
    /** Blockchain block number */
    block_number: number | null;
    /** Transaction timestamp */
    created_at: string | null;
}
/**
 * Ledger entry type for filtering movements.
 * Describes the direction/nature of the balance change.
 */
export type LedgerEntryType = "CREDIT" | "DEBIT" | "LOCK" | "UNLOCK" | "FEE";
/**
 * Transaction type for filtering movements.
 * Describes the reason/source of the movement.
 */
export type TransactionType = "DEPOSIT" | "WITHDRAWAL" | "TRADE" | "FEE" | "FUNDING" | "LIQUIDATION" | "INTEREST" | "REWARD";
/**
 * Query parameters for getting user movements
 */
export interface GetUserMovementsParams {
    /** Page number (starts from 1) */
    page?: number;
    /** Number of items per page (max 100) */
    page_size?: number;
    /** Filter by entry type (CREDIT, DEBIT, LOCK, UNLOCK, FEE) */
    entry_type?: LedgerEntryType;
    /** Filter by transaction type (DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD) */
    transaction_type?: TransactionType;
    /** Filter by asset ID (UUID) */
    asset_id?: string;
}
/**
 * Query parameters for getting user balances
 */
export interface GetUserBalancesParams {
    /** Page number (starts from 1) */
    page?: number;
    /** Number of items per page (max 100) */
    page_size?: number;
}
/**
 * Response from getting user movements
 */
export interface GetPaginatedUserMovementsResponse {
    /**
     * Latest movements from Redis cache (real-time, instant updates).
     * These are the most recent movements that may not yet be in PostgreSQL.
     * Only populated on page 1; empty for subsequent pages.
     */
    latest_movements?: LedgerMovement[];
    /** All movements from PostgreSQL (historical, paginated) */
    movements: LedgerMovement[];
    /** Current page number */
    page: number;
    /** Items per page */
    page_size: number;
    /** Total number of movements in PostgreSQL */
    total: number;
    /** Total number of pages */
    total_pages: number;
}
/**
 * Response from getting user balances
 */
export interface GetUserBalancesResponse {
    /** List of token balances for the user */
    balances: AccountBalance[];
    /** Total number of balances */
    total: number;
    /** Items per page */
    page_size: number;
    /** Current page number */
    page: number;
    /** Total number of pages */
    total_pages: number;
}
/**
 * Order information for recent orders.
 * Represents orders returned in the profile's recent_orders array.
 */
export interface ProfileOrder {
    /** Order identifier */
    id: string;
    /** Trading pair symbol (e.g., "ETH-USD") */
    symbol: string;
    /** Order side */
    side: OrderSide;
    /** Order type */
    order_type: OrderType;
    /** Order price (null for market orders) */
    price: string | null;
    /** Order quantity */
    quantity: string;
    /** Order status */
    status: OrderStatus;
    /** Time in force */
    time_in_force?: TimeInForce;
    /** Order creation timestamp (ISO string) */
    created_at: string;
    /** Order last update timestamp (ISO string) */
    updated_at?: string;
}
/**
 * Account balance for a specific token.
 * Returned by the single balance lookup endpoint.
 */
export interface AccountBalance {
    /** Asset ID (UUID for API calls) */
    asset_id: string;
    /** Token address */
    token: string;
    /** Token symbol */
    symbol: string | null;
    /** Decimal places for the token */
    decimals: number;
    /** Available balance for trading (normalized) */
    available_balance: string;
    /** Locked balance (in orders or pending operations, normalized) */
    locked_balance: string;
    /** Total balance (available + locked, normalized) */
    total_balance: string;
    /** Available balance in raw format (wei) */
    available_balance_raw: string;
    /** Locked balance in raw format (wei) */
    locked_balance_raw: string;
}
/**
 * A single user trade execution.
 */
export interface UserTrade {
    /** Trade unique identifier */
    trade_id: string;
    /** Trading pair identifier (UUID) */
    trading_pair_id: string;
    /** Execution price (as string to preserve precision) */
    price: string;
    /** Executed quantity (as string to preserve precision) */
    quantity: string;
    /** Quote volume (price * quantity, as string to preserve precision) */
    quote_volume: string;
    /** Side of the trade */
    side: OrderSide;
    /** Fee paid for this trade (as string to preserve precision) */
    fee: string;
    /** Timestamp when the trade was executed (ISO string) */
    executed_at: string;
}
/**
 * Query parameters for getting user trades
 */
export interface GetUserTradesParams {
    /** Page number (starts from 1) */
    page?: number;
    /** Number of items per page (max 100) */
    page_size?: number;
    /** Filter by trading pair ID (UUID) */
    trading_pair_id?: string;
}
/**
 * Response from getting user trades
 */
export interface GetUserTradesResponse {
    /** List of user trades */
    trades: UserTrade[];
    /** Current page number */
    page: number;
    /** Items per page */
    page_size: number;
    /** Total number of trades */
    total: number;
    /** Total number of pages */
    total_pages: number;
}
/**
 * Time period for portfolio stats and chart queries.
 */
export type PortfolioPeriod = "24h" | "7d" | "30d" | "all";
/**
 * Metric for portfolio chart queries.
 */
export type PortfolioMetric = "volume" | "pnl";
/**
 * A single data point in a portfolio chart time series.
 */
export interface PortfolioChartPoint {
    /** ISO 8601 timestamp for the bucket */
    timestamp: string;
    /** Metric value for the bucket (as string to preserve precision) */
    value: string;
}
/**
 * Portfolio chart time series response.
 * Returned by the /api/v1/accounts/me/portfolio/chart endpoint.
 */
export interface PortfolioChartResponse {
    /** The metric returned ("volume" | "pnl") */
    metric: PortfolioMetric;
    /** The period requested */
    period: PortfolioPeriod;
    /** Bucketed time series data points */
    data: PortfolioChartPoint[];
}
/**
 * Portfolio statistics for the authenticated user over a given period.
 * Returned by the /api/v1/accounts/me/portfolio endpoint.
 */
export interface PortfolioStats {
    /** Realized profit and loss (sum of CREDIT minus DEBIT from TRADE ledger entries) */
    pnl: string;
    /** Total trading volume (sum of quote_volume from trades) */
    volume: string;
    /** Maximum peak-to-trough drawdown on running PnL */
    max_drawdown: string;
    /** Total number of orders placed */
    total_orders: number;
    /** Total number of trades executed */
    total_trades: number;
    /** Total fees paid */
    fees_paid: string;
    /** Ratio of profitable trades to total trades */
    win_loss_ratio: string;
    /** Total equity in USDC terms (sum of all spot balances) */
    total_equity: string;
}
/**
 * User profile information returned by the /api/v1/accounts/me endpoint.
 */
export interface UserProfile {
    /** Unique identifier for the user */
    id: string;
    /** Wallet address of the user */
    address: string;
    /** Username of the user (can be null) */
    username: string | null;
    /** Account type (e.g., "master") */
    account_type: string;
    /** Whether the user can withdraw funds */
    can_withdraw: boolean;
    /** Taker fee rate in basis points */
    taker_fee_bps: number;
    /** Maker fee rate in basis points */
    maker_fee_bps: number;
    /** Account creation timestamp (ISO string) */
    created_at: string;
}
/**
 * Profile API interface.
 * Provides methods for fetching and managing user profile information.
 */
export interface ProfileAPI extends BaseAPI {
    /**
     * Get the current user's profile information.
     *
     * Fetches the profile data for the authenticated user using the /api/v1/accounts/me endpoint.
     * Requires a valid access token to be set.
     *
     * @returns Promise resolving to the user's profile information
     */
    getProfile(): Promise<UserProfile>;
    /**
     * Get the current user's ledger movements (transaction history) with pagination.
     *
     * Fetches the user's transaction history from the /api/v1/accounts/movements endpoint.
     * Requires a valid access token to be set.
     *
     * @param params - Optional query parameters for pagination and filtering
     * @param params.page - Page number (starts from 1)
     * @param params.limit - Number of items per page (max 100)
     * @param params.entry_type - Filter by entry type (CREDIT, DEBIT, LOCK, UNLOCK, FEE)
     * @param params.transaction_type - Filter by transaction type (DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD)
     * @param params.asset_id - Filter by asset ID (UUID)
     * @returns Promise resolving to paginated movements response
     */
    getPaginatedUserMovements(params?: GetUserMovementsParams): Promise<GetPaginatedUserMovementsResponse>;
    /**
     * Get the current user's token balances with pagination.
     *
     * Fetches the user's token balances from the /api/v1/accounts/balances endpoint.
     * Requires a valid access token to be set.
     *
     * @param params - Optional query parameters for pagination
     * @param params.limit - Number of items to return
     * @param params.offset - Number of items to skip
     * @returns Promise resolving to paginated balances response
     */
    getUserBalances(params?: GetUserBalancesParams): Promise<GetUserBalancesResponse>;
    /**
     * Get the current user's balance for a specific asset.
     *
     * Fetches the user's balance for a specific asset from the /api/v1/accounts/balances/{asset_id} endpoint.
     * Requires a valid access token to be set. If no balance exists for a valid asset, returns zero balances.
     *
     * @param assetId - The asset identifier (UUID)
     * @returns Promise resolving to the account balance for the asset
     */
    getUserBalanceByAssetId(assetId: string): Promise<AccountBalance>;
    /**
     * Get the current user's portfolio statistics for a given time period.
     *
     * Fetches aggregate stats from the /api/v1/accounts/me/portfolio endpoint.
     * Requires a valid access token to be set.
     *
     * @param period - Time period to scope the stats ("24h" | "7d" | "30d" | "all")
     * @returns Promise resolving to the user's portfolio statistics
     */
    getPortfolioStats(period: PortfolioPeriod): Promise<PortfolioStats>;
    /**
     * Get the current user's portfolio chart time series for a given period and metric.
     *
     * Fetches bucketed time series data from the /api/v1/accounts/me/portfolio/chart endpoint.
     * Requires a valid access token to be set.
     *
     * @param period - Time period ("24h" | "7d" | "30d" | "all")
     * @param metric - Metric to chart ("volume" | "pnl")
     * @returns Promise resolving to the portfolio chart response
     */
    getPortfolioChart(period: PortfolioPeriod, metric: PortfolioMetric): Promise<PortfolioChartResponse>;
    /**
     * Get the current user's trade history with pagination.
     *
     * Fetches the user's executed trades from the /api/v1/accounts/trades endpoint.
     * Requires a valid access token to be set.
     *
     * @param params - Optional query parameters for pagination and filtering
     * @param params.page - Page number (starts from 1)
     * @param params.limit - Number of items per page (max 100)
     * @param params.trading_pair_id - Filter by trading pair ID (UUID)
     * @returns Promise resolving to paginated trades response
     * @throws ValidationError If pagination params (page/limit) are invalid or trading_pair_id is not a valid UUID; this may occur before any network request.
     */
    getUserTrades(params?: GetUserTradesParams): Promise<GetUserTradesResponse>;
}