@0xmonaco/types 0.7.7 → 0.7.8

package/dist/api/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base API Types
+ *
+ * Common interface that all API implementations should inherit from.
+ * Provides standardized methods for token management and common functionality.
+ */
+/**
+ * Base API interface that all API implementations should inherit from.
+ * Provides common functionality for access token management.
+ */
+export interface BaseAPI {
+    /**
+     * Set the access token for authenticated requests.
+     *
+     * @param token - JWT access token
+     */
+    setAccessToken(token: string): void;
+}

package/dist/api/index.js

@@ -0,0 +1,6 @@
+/**
+ * Base API Types
+ *
+ * Common interface that all API implementations should inherit from.
+ * Provides standardized methods for token management and common functionality.
+ */

package/dist/applications/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Applications Types
+ *
+ * Types for application configuration operations.
+ */
+import type { BaseAPI } from "../api";
+import type { ApplicationConfigResponse } from "./responses";
+/**
+ * Applications API interface.
+ * Provides methods for retrieving application configuration.
+ */
+export interface ApplicationsAPI extends BaseAPI {
+    /**
+     * Gets the configuration for the authenticated application.
+     *
+     * Returns the application's configuration including allowed origins,
+     * webhook URL, and other settings. Requires valid authentication.
+     *
+     * @returns Promise resolving to the application configuration
+     */
+    getApplicationConfig(): Promise<ApplicationConfigResponse>;
+}
+export type { ApplicationConfigResponse } from "./responses";

package/dist/applications/index.js

@@ -0,0 +1,5 @@
+/**
+ * Applications Types
+ *
+ * Types for application configuration operations.
+ */

package/dist/applications/responses.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Applications Response Types
+ *
+ * Response types for application configuration operations.
+ */
+/**
+ * Response to an application configuration request.
+ */
+export interface ApplicationConfigResponse {
+    /** Unique identifier for the application */
+    id: string;
+    /** Human-readable name of the application */
+    name: string;
+    /** List of allowed origins for CORS */
+    allowedOrigins: string[];
+    /** Webhook URL for receiving events (optional) */
+    webhookUrl?: string;
+    /** Vault contract address */
+    vaultContractAddress: string;
+    /** Application client ID, embedded in on-chain deposit calls */
+    clientId: string;
+}

package/dist/applications/responses.js

@@ -0,0 +1,5 @@
+/**
+ * Applications Response Types
+ *
+ * Response types for application configuration operations.
+ */

package/dist/auth/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Auth Types
+ *
+ * Types for authentication operations including challenge creation,
+ * signature verification, and backend authentication.
+ */
+import type { BaseAPI } from "../api";
+import type { AuthState, BackendAuthResponse, ChallengeResponse, TokenRefreshResponse } from "./responses";
+/**
+ * Auth API interface.
+ * Provides methods for frontend and backend authentication.
+ * Handles challenge creation, signature verification, and backend auth.
+ */
+export interface AuthAPI extends BaseAPI {
+    /**
+     * Complete authentication flow for frontend applications.
+     *
+     * This method handles the entire authentication process:
+     * 1. Creates a challenge
+     * 2. Signs the challenge message
+     * 3. Verifies the signature and returns JWT tokens
+     *
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the authentication state with JWT tokens
+     */
+    authenticate(clientId: string): Promise<AuthState>;
+    /**
+     * Signs a challenge message using the wallet client.
+     *
+     * Signs the provided message using the wallet's private key.
+     * This is used in the authentication flow to prove ownership of the wallet.
+     *
+     * @param message - The message to sign
+     * @returns Promise resolving to the signature
+     */
+    signChallenge(message: string): Promise<string>;
+    /**
+     * Creates a challenge for frontend authentication.
+     * Generates a unique nonce and message that the user must sign with their wallet.
+     * @param address - Wallet address of the user
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the challenge response
+     */
+    createChallenge(address: string, clientId: string): Promise<ChallengeResponse>;
+    /**
+     * Verifies a signature for frontend authentication.
+     * Validates the signature against the challenge and returns JWT tokens.
+     * @param address - Wallet address of the user
+     * @param signature - Signature of the challenge message
+     * @param nonce - Nonce from the challenge response
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the authentication state with JWT tokens
+     */
+    verifySignature(address: string, signature: string, nonce: string, clientId: string): Promise<AuthState>;
+    /**
+     * Authenticates a backend service using a secret key.
+     * Returns JWT tokens for API access.
+     * @param secretKey - Secret key of the application
+     * @returns Promise resolving to the backend auth response with JWT tokens
+     */
+    authenticateBackend(secretKey: string): Promise<BackendAuthResponse>;
+    /**
+     * Refreshes an access token using a refresh token.
+     * @param refreshToken - The refresh token to use
+     * @returns Promise resolving to new access and refresh tokens
+     */
+    refreshToken(refreshToken: string): Promise<TokenRefreshResponse>;
+    /**
+     * Revokes the current session's refresh token.
+     * The server identifies the token to revoke from the access token in the Authorization header.
+     * @returns Promise resolving when the token is revoked
+     */
+    revokeToken(): Promise<void>;
+    /**
+     * Sets the wallet client for signing operations.
+     * Used when the wallet becomes available after SDK initialization.
+     * @param walletClient - The wallet client to set
+     */
+    setWalletClient(walletClient: unknown): void;
+}
+export type { ApplicationInfo, AuthState, BackendAuthResponse, ChallengeResponse, TokenRefreshResponse, User, } from "./responses";

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+/**
+ * Auth Types
+ *
+ * Types for authentication operations including challenge creation,
+ * signature verification, and backend authentication.
+ */

package/dist/auth/responses.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Auth Response Types
+ *
+ * Response types for authentication operations.
+ */
+/**
+ * Response to a challenge request.
+ */
+export interface ChallengeResponse {
+    /** Unique nonce for this challenge */
+    nonce: string;
+    /** Message to be signed by the user's wallet */
+    message: string;
+    /** Unix timestamp when the challenge expires */
+    expiresAt: number;
+}
+export interface User {
+    /** Unique identifier for the user */
+    id: string;
+    /** Wallet address of the user */
+    address: string;
+    /** Username of the user */
+    username?: string;
+}
+/**
+ * Authentication state containing all tokens and metadata
+ *
+ * Returned by authentication methods and contains the tokens needed for API access.
+ */
+export interface AuthState {
+    /** JWT access token for authenticated requests */
+    accessToken: string;
+    /** JWT refresh token for token renewal and revocation */
+    refreshToken: string;
+    /** Unix timestamp (in seconds) when the access token expires */
+    expiresAt: number;
+    /** Information about the authenticated user */
+    user: User;
+}
+export interface ApplicationInfo {
+    /** Unique identifier for the application */
+    id: string;
+    /** Human-readable name of the application */
+    name: string;
+    /** Client ID for frontend authentication */
+    clientId: string;
+}
+/**
+ * Response to a backend authentication request.
+ */
+export interface BackendAuthResponse {
+    /** JWT access token for authenticated requests */
+    accessToken: string;
+    /** Unix timestamp when the access token expires */
+    expiresAt: number;
+    /** Information about the application */
+    application: ApplicationInfo;
+}
+/**
+ * Response to a token refresh request.
+ */
+export interface TokenRefreshResponse {
+    /** New JWT access token */
+    accessToken: string;
+    /** Unix timestamp when the access token expires */
+    expiresAt: number;
+}

package/dist/auth/responses.js

@@ -0,0 +1,5 @@
+/**
+ * Auth Response Types
+ *
+ * Response types for authentication operations.
+ */

package/dist/contracts/balances.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Contract Balance Types
+ *
+ * Types for contract balance management and token information.
+ */
+import type { Address } from "viem";
+/**
+ * Type representing a token in the Monaco Markets protocol.
+ * Contains essential token metadata and contract information.
+ *
+ * @property address - Token contract address
+ * @property symbol - Token symbol (e.g. "ETH", "USDC")
+ * @property decimals - Number of decimal places for token amounts
+ * @property name - Full token name
+ */
+export interface Token {
+    /** Token contract address */
+    address: Address;
+    /** Token symbol (e.g. "ETH", "USDC") */
+    symbol: string;
+    /** Number of decimal places for token amounts */
+    decimals: number;
+    /** Full token name */
+    name: string;
+}
+/**
+ * Type representing a user's balance for a specific token in contract storage.
+ *
+ * @property token - Token address
+ * @property available - Available balance for trading
+ * @property locked - Locked balance in open orders
+ * @property total - Total balance (available + locked)
+ */
+export interface UserBalance {
+    /** Token address */
+    token: string;
+    /** Available balance for trading */
+    available: bigint;
+    /** Locked balance in open orders */
+    locked: bigint;
+    /** Total balance (available + locked) */
+    total: bigint;
+}

package/dist/contracts/balances.js

@@ -0,0 +1,5 @@
+/**
+ * Contract Balance Types
+ *
+ * Types for contract balance management and token information.
+ */

package/dist/contracts/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Contract Types
+ *
+ * Types for contract addresses, instances, and contract-related operations.
+ */
+import type { CONTRACT_ABIS } from "@0xmonaco/contracts";
+import type { GetContractReturnType } from "viem";
+/**
+ * Interface for all contract addresses in the Monaco Markets protocol.
+ *
+ * @property VAULT - Vault contract address for managing user balances
+ */
+export interface ContractAddresses {
+    /** Vault contract address for managing user balances */
+    VAULT: string;
+}
+/**
+ * Type representing all contract instances.
+ * Maps contract names to their typed instances with full ABI type safety.
+ *
+ * @property vault - Vault contract instance for managing user balances
+ */
+export type ContractInstances = {
+    /** Vault contract instance for managing user balances */
+    vault: GetContractReturnType<typeof CONTRACT_ABIS.vault>;
+};
+export type { Token, UserBalance } from "./balances";

package/dist/contracts/index.js

@@ -0,0 +1,5 @@
+/**
+ * Contract Types
+ *
+ * Types for contract addresses, instances, and contract-related operations.
+ */

package/dist/fees/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Fees Types
+ *
+ * Types for fees operations including fee simulation.
+ */
+import type { BaseAPI } from "../api/index";
+import type { SimulateFeeParams, SimulateFeeResponse } from "./responses";
+/**
+ * Fees API interface.
+ * Provides methods for simulating and calculating trading fees.
+ */
+export interface FeesAPI extends BaseAPI {
+    /**
+     * Simulate fees for an order before placing it.
+     * Returns exact fees for that specific order.
+     *
+     * @param params - Parameters for fee simulation
+     * @param params.trading_pair_id - Trading pair ID
+     * @param params.side - Order side ("BUY" or "SELL")
+     * @param params.price - Price per unit
+     * @param params.quantity - Quantity to trade
+     * @returns Promise resolving to fee simulation details
+     *
+     * @example
+     * ```typescript
+     * const feeDetails = await feesAPI.simulateFees({
+     *   trading_pair_id: "123e4567-e89b-12d3-a456-426614174000",
+     *   side: "BUY",
+     *   price: "40000.00",
+     *   quantity: "0.5"
+     * });
+     * console.log(`Total taker fees: ${feeDetails.total_taker_fees}`);
+     * console.log(`Taker must pay: ${feeDetails.taker_total_payment}`);
+     * ```
+     */
+    simulateFees(params: SimulateFeeParams): Promise<SimulateFeeResponse>;
+}
+export type { SimulateFeeParams, SimulateFeeResponse } from "./responses";
+export { SimulateFeeParamsSchema, SimulateFeeResponseSchema } from "./responses";

package/dist/fees/index.js

@@ -0,0 +1,6 @@
+/**
+ * Fees Types
+ *
+ * Types for fees operations including fee simulation.
+ */
+export { SimulateFeeParamsSchema, SimulateFeeResponseSchema } from "./responses";

package/dist/fees/responses.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Fees Response Types
+ *
+ * Types for fees-related API responses.
+ * All types are derived from Zod schemas for runtime validation.
+ */
+import { z } from "zod";
+/**
+ * Zod schema for simulating order fees parameters
+ */
+export declare const SimulateFeeParamsSchema: z.ZodObject<{
+    trading_pair_id: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    price: z.ZodString;
+    quantity: z.ZodString;
+    order_type: z.ZodOptional<z.ZodEnum<{
+        LIMIT: "LIMIT";
+        MARKET: "MARKET";
+    }>>;
+    slippage_tolerance_bps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Zod schema for fee simulation response
+ */
+export declare const SimulateFeeResponseSchema: z.ZodObject<{
+    application_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    application_taker_fee: z.ZodString;
+    application_taker_fee_bps: z.ZodNumber;
+    buy_order_lock_amount: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    maker_total_receipt: z.ZodString;
+    monaco_maker_rebate: z.ZodString;
+    monaco_maker_rebate_bps: z.ZodNumber;
+    monaco_taker_fee: z.ZodString;
+    monaco_taker_fee_bps: z.ZodNumber;
+    notional: z.ZodString;
+    taker_total_payment: z.ZodString;
+    total_taker_fees: z.ZodString;
+    max_quantity: z.ZodNullable<z.ZodString>;
+    max_quantity_raw: z.ZodNullable<z.ZodString>;
+    slippage_tolerance_bps: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Parameters for simulating order fees
+ * @remarks Type is inferred from SimulateFeeParamsSchema
+ */
+export type SimulateFeeParams = z.infer<typeof SimulateFeeParamsSchema>;
+/**
+ * Response with detailed fee breakdown for simulating order fees
+ * @remarks Type is inferred from SimulateFeeResponseSchema
+ */
+export type SimulateFeeResponse = z.infer<typeof SimulateFeeResponseSchema>;

package/dist/fees/responses.js

@@ -0,0 +1,86 @@
+/**
+ * Fees Response Types
+ *
+ * Types for fees-related API responses.
+ * All types are derived from Zod schemas for runtime validation.
+ */
+import { z } from "zod";
+/**
+ * Zod schema for simulating order fees parameters
+ */
+export const SimulateFeeParamsSchema = z
+    .object({
+    /** Trading pair ID */
+    trading_pair_id: z.string().trim().min(1, "Trading pair ID is required and cannot be empty"),
+    /** Order side: "BUY" or "SELL" */
+    side: z.enum(["BUY", "SELL"], {
+        message: "Order side is required and must be either 'BUY' or 'SELL'",
+    }),
+    /** Price per unit */
+    price: z
+        .string()
+        .trim()
+        .min(1, "Price is required and cannot be empty")
+        .refine((val) => !Number.isNaN(Number(val)), "Price must be a valid number")
+        .refine((val) => Number(val) > 0, "Price must be greater than 0"),
+    /** Quantity to trade */
+    quantity: z
+        .string()
+        .trim()
+        .min(1, "Quantity is required and cannot be empty")
+        .refine((val) => !Number.isNaN(Number(val)), "Quantity must be a valid number")
+        .refine((val) => Number(val) > 0, "Quantity must be greater than 0"),
+    /** Order type: "LIMIT" (default) or "MARKET". MARKET orders include a slippage buffer in the lock amount. */
+    order_type: z.enum(["LIMIT", "MARKET"]).optional(),
+    /** Slippage tolerance in basis points (0–1000). Only valid for MARKET orders. Default: 500 (5%). */
+    slippage_tolerance_bps: z
+        .number()
+        .int()
+        .min(0, "Slippage tolerance must be between 0 and 1000 bps")
+        .max(1000, "Slippage tolerance must be between 0 and 1000 bps")
+        .optional(),
+})
+    .superRefine((data, ctx) => {
+    if (data.slippage_tolerance_bps !== undefined && data.order_type !== "MARKET") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "slippage_tolerance_bps is only valid when order_type is MARKET",
+            path: ["slippage_tolerance_bps"],
+        });
+    }
+});
+/**
+ * Zod schema for fee simulation response
+ */
+export const SimulateFeeResponseSchema = z.object({
+    /** Application name (if applicable) */
+    application_name: z.string().nullable().optional(),
+    /** Frontend application taker fee */
+    application_taker_fee: z.string(),
+    /** Application fee in basis points */
+    application_taker_fee_bps: z.number(),
+    /** Amount to lock for BUY orders (null for `SELL`) */
+    buy_order_lock_amount: z.string().nullable().optional(),
+    /** Total amount maker receives */
+    maker_total_receipt: z.string(),
+    /** Monaco protocol maker rebate (negative = rebate) */
+    monaco_maker_rebate: z.string(),
+    /** Monaco maker rebate in basis points */
+    monaco_maker_rebate_bps: z.number(),
+    /** Monaco protocol taker fee */
+    monaco_taker_fee: z.string(),
+    /** Monaco taker fee in basis points */
+    monaco_taker_fee_bps: z.number(),
+    /** Notional value (price * quantity) */
+    notional: z.string(),
+    /** Total amount taker must pay */
+    taker_total_payment: z.string(),
+    /** Total taker fees (monaco + application) */
+    total_taker_fees: z.string(),
+    /** Maximum quantity affordable at the given price, accounting for fees (null if not authenticated or balance unavailable) */
+    max_quantity: z.string().nullable(),
+    /** Maximum quantity in RAW (smallest unit) format */
+    max_quantity_raw: z.string().nullable(),
+    /** Slippage tolerance used in the calculation, echoed back for MARKET orders (null for LIMIT orders) */
+    slippage_tolerance_bps: z.number().nullable(),
+});

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Monaco Types Package
+ *
+ * This package provides TypeScript types for the Monaco protocol.
+ * It includes SDK types, vault types, trading types, contract types, and common types.
+ */
+export * from "./api";
+export * from "./applications";
+export * from "./auth";
+export * from "./contracts";
+export * from "./fees";
+export * from "./margin-accounts";
+export * from "./market";
+export * from "./positions";
+export * from "./profile";
+export * from "./sdk";
+export * from "./trading";
+export * from "./validation";
+export * from "./vault";
+export * from "./websocket";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * Monaco Types Package
+ *
+ * This package provides TypeScript types for the Monaco protocol.
+ * It includes SDK types, vault types, trading types, contract types, and common types.
+ */
+// Export everything from all modules
+export * from "./api";
+export * from "./applications";
+export * from "./auth";
+export * from "./contracts";
+export * from "./fees";
+export * from "./margin-accounts";
+export * from "./market";
+export * from "./positions";
+export * from "./profile";
+export * from "./sdk";
+export * from "./trading";
+export * from "./validation";
+export * from "./vault";
+export * from "./websocket";

package/dist/margin-accounts/index.d.ts

@@ -0,0 +1,110 @@
+import type { BaseAPI } from "../api";
+import type { OrderSide, OrderType, PositionSide } from "../trading";
+export interface MarginAccountSummary {
+    margin_account_id: string;
+    label?: string;
+    account_state: string;
+    equity: string;
+    initial_margin_required: string;
+    maintenance_margin_required: string;
+    free_collateral: string;
+    withdrawable_collateral: string;
+    total_position_notional: string;
+    unrealized_pnl: string;
+    realized_pnl: string;
+    updated_at: string;
+}
+export interface ListMarginAccountsParams {
+    page?: number;
+    page_size?: number;
+    state?: string;
+}
+export interface ListMarginAccountsResponse {
+    accounts: MarginAccountSummary[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+export interface CreateMarginAccountRequest {
+    label?: string;
+    collateralAsset?: string;
+}
+export interface CreateMarginAccountResponse {
+    margin_account_id: string;
+    label?: string;
+    account_state: string;
+    collateral_asset: string;
+    created_at: string;
+}
+export interface GetAvailableCollateralParams {
+    asset?: string;
+}
+export interface GetAvailableCollateralResponse {
+    asset: string;
+    wallet_available: string;
+    wallet_locked: string;
+    margin_transferable?: string;
+}
+export interface TransferCollateralRequest {
+    asset: string;
+    amount: string;
+}
+export interface TransferCollateralResponse {
+    movement_id: string;
+    margin_account_id: string;
+    asset: string;
+    amount: string;
+    status: string;
+    new_equity: string;
+    new_total_collateral_value: string;
+    new_withdrawable_collateral: string;
+}
+export interface GetMarginAccountMovementsParams {
+    movement_type?: string;
+    page?: number;
+    page_size?: number;
+}
+export interface MarginAccountMovement {
+    movement_id: string;
+    margin_account_id: string;
+    movement_type: string;
+    asset: string;
+    amount: string;
+    created_at: string;
+}
+export interface GetMarginAccountMovementsResponse {
+    movements: MarginAccountMovement[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+export interface SimulateOrderRiskRequest {
+    tradingPairId: string;
+    side: OrderSide;
+    positionSide: PositionSide;
+    orderType: OrderType;
+    price?: string;
+    quantity: string;
+    leverage: string;
+    reduceOnly?: boolean;
+}
+export interface SimulateOrderRiskResponse {
+    accepted: boolean;
+    reject_reason?: string;
+    equity_after: string;
+    initial_margin_required_after: string;
+    maintenance_margin_required_after: string;
+    free_collateral_after: string;
+    estimated_fee?: string;
+    estimated_liquidation_price?: string;
+}
+export interface MarginAccountsAPI extends BaseAPI {
+    listMarginAccounts(params?: ListMarginAccountsParams): Promise<ListMarginAccountsResponse>;
+    createMarginAccount(request?: CreateMarginAccountRequest): Promise<CreateMarginAccountResponse>;
+    getMarginAccountSummary(marginAccountId: string): Promise<MarginAccountSummary>;
+    getAvailableCollateral(params?: GetAvailableCollateralParams): Promise<GetAvailableCollateralResponse>;
+    transferCollateralToMarginAccount(marginAccountId: string, request: TransferCollateralRequest): Promise<TransferCollateralResponse>;
+    transferCollateralFromMarginAccount(marginAccountId: string, request: TransferCollateralRequest): Promise<TransferCollateralResponse>;
+    getMarginAccountMovements(marginAccountId: string, params?: GetMarginAccountMovementsParams): Promise<GetMarginAccountMovementsResponse>;
+    simulateOrderRisk(marginAccountId: string, request: SimulateOrderRiskRequest): Promise<SimulateOrderRiskResponse>;
+}