@0xmonaco/types 0.8.7 → 0.8.10

package/dist/api/index.d.ts

@@ -2,17 +2,25 @@
  * Base API Types
  *
  * Common interface that all API implementations should inherit from.
- * Provides standardized methods for token management and common functionality.
+ * Provides standardized methods for session-key management and common functionality.
  */
+import type { SessionCredentials } from "../auth/responses";
 /**
  * Base API interface that all API implementations should inherit from.
- * Provides common functionality for access token management.
+ * Provides common functionality for session-key management.
  */
 export interface BaseAPI {
     /**
-     * Set the access token for authenticated requests.
+     * Set (or clear) the session keypair used to sign authenticated requests.
      *
-     * @param token - JWT access token
+     * @param credentials - Hex-encoded session keypair, or `undefined` to clear.
      */
-    setAccessToken(token: string): void;
+    setSessionKeypair(credentials: SessionCredentials | undefined): void;
+    /**
+     * Set (or clear) the application secret key used for backend-authenticated
+     * requests. When set, it is sent in the `x-server-key` header.
+     *
+     * @param serverKey - The application secret key (`sk_...`), or `undefined` to clear.
+     */
+    setServerKey(serverKey: string | undefined): void;
 }

package/dist/api/index.js

@@ -2,5 +2,5 @@
  * Base API Types
  *
  * Common interface that all API implementations should inherit from.
- * Provides standardized methods for token management and common functionality.
+ * Provides standardized methods for session-key management and common functionality.
  */

package/dist/applications/index.d.ts

@@ -1,23 +1,65 @@
 /**
  * Applications Types
  *
- * Types for application configuration operations.
+ * Types for application configuration and the backend-authenticated
+ * application reporting endpoints.
  */
 import type { BaseAPI } from "../api";
-import type { ApplicationConfigResponse } from "./responses";
+import type { GetAppStatsParams, ListAppBalancesParams, ListAppMovementsParams, ListAppOrdersParams, ListAppUsersParams } from "./requests";
+import type { ApplicationConfigResponse, GetAppStatsResponse, ListAppBalancesResponse, ListAppMovementsResponse, ListAppOrdersResponse, ListAppUsersResponse } from "./responses";
 /**
  * Applications API interface.
- * Provides methods for retrieving application configuration.
+ *
+ * `getApplicationConfig` is session-authenticated (signed with the session
+ * key). The reporting methods are backend-authenticated: set the application's
+ * secret key with {@link BaseAPI.setServerKey} before calling them — each
+ * request sends it in the `x-server-key` header.
  */
 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.
+     * webhook URL, and other settings. Requires valid session authentication.
      *
      * @returns Promise resolving to the application configuration
      */
     getApplicationConfig(): Promise<ApplicationConfigResponse>;
+    /**
+     * Lists orders placed by the application's users. Backend-authenticated.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of orders
+     */
+    listApplicationOrders(params?: ListAppOrdersParams): Promise<ListAppOrdersResponse>;
+    /**
+     * Lists the application's users. Backend-authenticated.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of users
+     */
+    listApplicationUsers(params?: ListAppUsersParams): Promise<ListAppUsersResponse>;
+    /**
+     * Lists ledger movements for the application's users. Backend-authenticated.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of movements
+     */
+    listApplicationMovements(params?: ListAppMovementsParams): Promise<ListAppMovementsResponse>;
+    /**
+     * Lists user balances held within the application. Backend-authenticated.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of balances
+     */
+    listApplicationBalances(params?: ListAppBalancesParams): Promise<ListAppBalancesResponse>;
+    /**
+     * Gets aggregate volume and fee stats for the application. Backend-authenticated.
+     *
+     * @param params - Optional `since` filter
+     * @returns Promise resolving to the application stats
+     */
+    getApplicationStats(params?: GetAppStatsParams): Promise<GetAppStatsResponse>;
 }
-export type { ApplicationConfigResponse } from "./responses";
+export type { GetAppStatsParams, ListAppBalancesParams, ListAppMovementsParams, ListAppOrdersParams, ListAppUsersParams } from "./requests";
+export type { AppBalance, ApplicationConfigResponse, AppMovement, AppOrder, AppUser, GetAppStatsResponse, ListAppBalancesResponse, ListAppMovementsResponse, ListAppOrdersResponse, ListAppUsersResponse, } from "./responses";

package/dist/applications/index.js

@@ -1,5 +1,6 @@
 /**
  * Applications Types
  *
- * Types for application configuration operations.
+ * Types for application configuration and the backend-authenticated
+ * application reporting endpoints.
  */

package/dist/applications/requests.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Applications Request Types
+ *
+ * Query parameters for the backend-authenticated application reporting
+ * endpoints. Field names match the wire (snake_case) so they can be passed
+ * straight through to the query string.
+ */
+/**
+ * Query parameters for listing application orders.
+ */
+export interface ListAppOrdersParams {
+    /** Page number (starts from 1) */
+    page?: number;
+    /** Items per page (max 100) */
+    page_size?: number;
+    /** Filter by order status (e.g. SUBMITTED, PARTIALLY_FILLED, FILLED, SETTLED, CANCELLED, EXPIRED, REJECTED) */
+    status?: string;
+    /** Filter by user UUID */
+    user_id?: string;
+    /** Filter by trading pair UUID */
+    trading_pair_id?: string;
+    /** Filter by order side: BUY or SELL */
+    side?: string;
+    /** Filter by order type (e.g. LIMIT, MARKET, STOP_LOSS, TAKE_PROFIT, STOP_LIMIT, TRAILING_STOP) */
+    order_type?: string;
+}
+/**
+ * Query parameters for listing application users.
+ */
+export interface ListAppUsersParams {
+    /** Page number (starts from 1) */
+    page?: number;
+    /** Items per page (max 100) */
+    page_size?: number;
+    /** Filter by active status */
+    is_active?: boolean;
+    /** Filter by account type: master or sub */
+    account_type?: string;
+    /** Filter by wallet address (partial match, case-insensitive) */
+    address?: string;
+}
+/**
+ * Query parameters for listing application movements.
+ */
+export interface ListAppMovementsParams {
+    /** Page number (starts from 1) */
+    page?: number;
+    /** Items per page (max 100) */
+    page_size?: number;
+    /** Filter by user UUID */
+    user_id?: string;
+    /** Filter by transaction type (e.g. DEPOSIT, WITHDRAWAL, TRADE, FEE, FUNDING, LIQUIDATION, INTEREST, REWARD) */
+    transaction_type?: string;
+    /** Filter by entry type (e.g. CREDIT, DEBIT, LOCK, UNLOCK, FEE) */
+    entry_type?: string;
+    /** Filter by asset UUID */
+    asset_id?: string;
+}
+/**
+ * Query parameters for listing application balances.
+ */
+export interface ListAppBalancesParams {
+    /** Page number (starts from 1) */
+    page?: number;
+    /** Items per page (max 100) */
+    page_size?: number;
+    /** Filter by user UUID */
+    user_id?: string;
+    /** Filter by asset UUID */
+    asset_id?: string;
+}
+/**
+ * Query parameters for application stats.
+ */
+export interface GetAppStatsParams {
+    /** ISO 8601 datetime to filter stats from (e.g. 2026-01-01T00:00:00Z). Omit for all-time. */
+    since?: string;
+}

package/dist/applications/requests.js

@@ -0,0 +1,7 @@
+/**
+ * Applications Request Types
+ *
+ * Query parameters for the backend-authenticated application reporting
+ * endpoints. Field names match the wire (snake_case) so they can be passed
+ * straight through to the query string.
+ */

package/dist/applications/responses.d.ts

@@ -1,7 +1,9 @@
 /**
  * Applications Response Types
  *
- * Response types for application configuration operations.
+ * Response types for application configuration operations and the
+ * backend-authenticated application reporting endpoints. Reporting types use
+ * the wire shape (snake_case); optional fields are `null` rather than omitted.
  */
 /**
  * Response to an application configuration request.
@@ -20,3 +22,211 @@ export interface ApplicationConfigResponse {
     /** Application client ID, embedded in on-chain deposit calls */
     clientId: string;
 }
+/**
+ * One order belonging to an application's users.
+ */
+export interface AppOrder {
+    /** Order UUID */
+    id: string;
+    /** User UUID who placed the order */
+    user_id: string;
+    /** Trading pair UUID */
+    trading_pair_id: string;
+    /** Order type: LIMIT, MARKET, STOP_LOSS, TAKE_PROFIT, STOP_LIMIT, or TRAILING_STOP */
+    order_type: string;
+    /** Order side: BUY or SELL */
+    side: string;
+    /** Order price (null for market orders) */
+    price: string | null;
+    /** Order quantity (normalized for display) */
+    quantity: string;
+    /** Order quantity in raw format (for precision) */
+    quantity_raw: string;
+    /** Filled quantity (normalized for display) */
+    filled_quantity: string | null;
+    /** Filled quantity in raw format */
+    filled_quantity_raw: string | null;
+    /** Volume-weighted average fill price */
+    average_fill_price: string | null;
+    /** Order status */
+    status: string;
+    /** Trading mode: SPOT or MARGIN */
+    trading_mode: string;
+    /** Time in force: GTC, IOC, or FOK */
+    time_in_force: string | null;
+    /** Order creation timestamp (ISO 8601) */
+    created_at: string | null;
+    /** Order last update timestamp (ISO 8601) */
+    updated_at: string | null;
+}
+/**
+ * One user belonging to an application.
+ */
+export interface AppUser {
+    /** User UUID */
+    id: string;
+    /** Wallet address */
+    address: string;
+    /** Display username */
+    username: string | null;
+    /** Account type: master or sub */
+    account_type: string;
+    /** Whether the user is allowed to withdraw */
+    can_withdraw: boolean;
+    /** Account creation timestamp (ISO 8601) */
+    created_at: string | null;
+    /** Email address */
+    email: string | null;
+    /** Whether the user account is active */
+    is_active: boolean | null;
+    /** Whether the user is banned */
+    is_banned: boolean | null;
+    /** Master account ID (for sub-accounts) */
+    master_account_id: string | null;
+    /** Last update timestamp (ISO 8601) */
+    updated_at: string | null;
+}
+/**
+ * One ledger movement (deposit, withdrawal, trade, etc.) for an application.
+ */
+export interface AppMovement {
+    /** Transaction amount */
+    amount: string;
+    /** Balance after this transaction */
+    balance_after: string | null;
+    /** Balance before this transaction */
+    balance_before: string | null;
+    /** Balance UUID this movement affects */
+    balance_id: string;
+    /** Blockchain block number */
+    block_number: number | null;
+    /** Transaction timestamp (ISO 8601) */
+    created_at: string | null;
+    /** Human readable description */
+    description: string | null;
+    /** Type of ledger entry */
+    entry_type: string;
+    /** Movement UUID */
+    id: string;
+    /** Locked balance after transaction */
+    locked_after: string | null;
+    /** Locked balance before transaction */
+    locked_before: string | null;
+    /** Reference identifier for related operations */
+    reference_id: string | null;
+    /** Reference type */
+    reference_type: string | null;
+    /** Token address */
+    token: string;
+    /** Type of transaction */
+    transaction_type: string;
+    /** Blockchain transaction hash */
+    tx_hash: string | null;
+    /** User UUID who owns this movement */
+    user_id: string;
+}
+/**
+ * One user balance held within an application.
+ */
+export interface AppBalance {
+    /** Available balance for trading */
+    available_balance: string;
+    /** Balance creation timestamp (ISO 8601) */
+    created_at: string | null;
+    /** Token decimals */
+    decimals: number;
+    /** Balance UUID */
+    id: string;
+    /** Last sync timestamp (ISO 8601) */
+    last_sync_at: string | null;
+    /** Last sync block number */
+    last_sync_block: number | null;
+    /** Locked balance */
+    locked_balance: string;
+    /** On-chain balance */
+    on_chain_balance: string;
+    /** Token symbol */
+    symbol: string | null;
+    /** Token address */
+    token: string;
+    /** Total balance */
+    total_balance: string;
+    /** Balance last update timestamp (ISO 8601) */
+    updated_at: string | null;
+    /** User UUID who owns this balance */
+    user_id: string;
+}
+/**
+ * Paginated list of application orders.
+ */
+export interface ListAppOrdersResponse {
+    orders: AppOrder[];
+    /** Total matching orders */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    page_size: number;
+    /** Total number of pages */
+    total_pages: number;
+}
+/**
+ * Paginated list of application users.
+ */
+export interface ListAppUsersResponse {
+    users: AppUser[];
+    /** Total number of users */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    page_size: number;
+    /** Total number of pages */
+    total_pages: number;
+}
+/**
+ * Paginated list of application movements.
+ */
+export interface ListAppMovementsResponse {
+    movements: AppMovement[];
+    /** Total matching movements */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    page_size: number;
+    /** Total number of pages */
+    total_pages: number;
+}
+/**
+ * Paginated list of application balances.
+ */
+export interface ListAppBalancesResponse {
+    balances: AppBalance[];
+    /** Total matching balances */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    page_size: number;
+    /** Total number of pages */
+    total_pages: number;
+}
+/**
+ * Aggregate volume and fee stats for an application.
+ *
+ * Stats are scoped to trades where the application's users were the taker.
+ * All monetary values are normalized (human-readable quote token units).
+ */
+export interface GetAppStatsResponse {
+    /** Total quote volume for trades where this application's users were the taker */
+    volume: string;
+    /** Total maker fees collected */
+    maker_fee: string;
+    /** Total taker fees collected */
+    taker_fee: string;
+    /** Application revenue share from taker fees */
+    application_taker_fee: string;
+    /** Total number of trades */
+    trade_count: number;
+}

package/dist/applications/responses.js

@@ -1,5 +1,7 @@
 /**
  * Applications Response Types
  *
- * Response types for application configuration operations.
+ * Response types for application configuration operations and the
+ * backend-authenticated application reporting endpoints. Reporting types use
+ * the wire shape (snake_case); optional fields are `null` rather than omitted.
  */

package/dist/auth/index.d.ts

@@ -1,27 +1,28 @@
 /**
  * Auth Types
  *
- * Types for authentication operations including challenge creation,
- * signature verification, and backend authentication.
+ * Types for wallet authentication operations including challenge creation,
+ * signature verification, and session lifecycle.
  */
 import type { BaseAPI } from "../api";
-import type { AuthState, BackendAuthResponse, ChallengeResponse, TokenRefreshResponse } from "./responses";
+import type { AuthState, ChallengeResponse, SessionCredentials, SessionRefreshResponse } from "./responses";
 /**
  * Auth API interface.
- * Provides methods for frontend and backend authentication.
- * Handles challenge creation, signature verification, and backend auth.
+ * Provides methods for wallet-based authentication.
+ * Handles challenge creation, signature verification, and session lifecycle.
  */
 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
+     * 1. Generates a fresh ed25519 session keypair locally
+     * 2. Creates a challenge that commits to the session public key
+     * 3. Signs the challenge message with the wallet
+     * 4. Verifies the signature, registering the session public key
      *
      * @param clientId - Client ID of the application
-     * @returns Promise resolving to the authentication state with JWT tokens
+     * @returns Promise resolving to the authentication state (including the session keypair)
      */
     authenticate(clientId: string): Promise<AuthState>;
     /**
@@ -36,41 +37,38 @@ export interface AuthAPI extends BaseAPI {
     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.
+     * Generates a unique nonce and a message (embedding the session public key)
+     * that the user must sign with their wallet.
      * @param address - Wallet address of the user
      * @param clientId - Client ID of the application
+     * @param sessionPublicKey - Hex-encoded ed25519 session public key to bind
      * @returns Promise resolving to the challenge response
      */
-    createChallenge(address: string, clientId: string): Promise<ChallengeResponse>;
+    createChallenge(address: string, clientId: string, sessionPublicKey: string): Promise<ChallengeResponse>;
     /**
      * Verifies a signature for frontend authentication.
-     * Validates the signature against the challenge and returns JWT tokens.
+     * Validates the wallet signature against the challenge and registers the
+     * session public key, returning the new authentication state.
      * @param address - Wallet address of the user
-     * @param signature - Signature of the challenge message
+     * @param signature - Wallet 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
+     * @param session - The locally-generated session keypair (hex-encoded)
+     * @returns Promise resolving to the authentication state
      */
-    verifySignature(address: string, signature: string, nonce: string, clientId: string): Promise<AuthState>;
+    verifySignature(address: string, signature: string, nonce: string, clientId: string, session: SessionCredentials): 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
+     * Extends the current session's expiry. The request is signed with the
+     * active session key (set via {@link setSessionKeypair}).
+     * @returns Promise resolving to the new expiry
      */
-    authenticateBackend(secretKey: string): Promise<BackendAuthResponse>;
+    refreshSession(): Promise<SessionRefreshResponse>;
     /**
-     * Refreshes an access token using a refresh token.
-     * @param refreshToken - The refresh token to use
-     * @returns Promise resolving to new access and refresh tokens
+     * Revokes the current session. The request is signed with the active session
+     * key, and the server deletes the matching session row.
+     * @returns Promise resolving when the session is revoked
      */
-    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>;
+    revokeSession(): Promise<void>;
     /**
      * Sets the wallet client for signing operations.
      * Used when the wallet becomes available after SDK initialization.
@@ -78,4 +76,4 @@ export interface AuthAPI extends BaseAPI {
      */
     setWalletClient(walletClient: unknown): void;
 }
-export type { ApplicationInfo, AuthState, BackendAuthResponse, ChallengeResponse, TokenRefreshResponse, User, } from "./responses";
+export type { ApplicationInfo, AuthState, ChallengeResponse, SessionCredentials, SessionRefreshResponse, User, } from "./responses";

package/dist/auth/index.js

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

package/dist/auth/responses.d.ts

@@ -23,16 +23,22 @@ export interface User {
     username?: string;
 }
 /**
- * Authentication state containing all tokens and metadata
+ * Authentication state for the noncustodial session-key scheme.
  *
- * Returned by authentication methods and contains the tokens needed for API access.
+ * On login the SDK generates an ed25519 keypair locally and registers the
+ * public key with the server. Subsequent requests are signed with the private
+ * key — the server never holds a credential that can impersonate the user.
+ *
+ * The private key is the long-lived credential: persist it (e.g. localStorage,
+ * same risk profile as a JWT) to survive page reloads without re-prompting the
+ * wallet. When the session expires, call `refreshAuth()` or re-`login()`.
  */
 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 */
+    /** Hex-encoded (64 chars) ed25519 session public key registered with the server */
+    sessionPublicKey: string;
+    /** Hex-encoded (64 chars) ed25519 session private key used to sign requests */
+    sessionPrivateKey: string;
+    /** Unix timestamp (in seconds) when the session expires */
     expiresAt: number;
     /** Information about the authenticated user */
     user: User;
@@ -46,22 +52,19 @@ export interface ApplicationInfo {
     clientId: string;
 }
 /**
- * Response to a backend authentication request.
+ * A session keypair, hex-encoded. The private key is used to sign requests;
+ * the public key identifies the session server-side.
  */
-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;
+export interface SessionCredentials {
+    /** Hex-encoded (64 chars) ed25519 public key */
+    publicKey: string;
+    /** Hex-encoded (64 chars) ed25519 private key */
+    privateKey: string;
 }
 /**
- * Response to a token refresh request.
+ * Response to a session refresh request — extends the session's expiry.
  */
-export interface TokenRefreshResponse {
-    /** New JWT access token */
-    accessToken: string;
-    /** Unix timestamp when the access token expires */
+export interface SessionRefreshResponse {
+    /** Unix timestamp when the session expires after refresh */
     expiresAt: number;
 }

package/dist/delegated-agents/index.d.ts

@@ -33,11 +33,26 @@ export interface DelegatedAgent {
 export interface ListDelegatedAgentsResponse {
     agents: DelegatedAgent[];
 }
+export interface DelegatedAgentOwner {
+    owner_user_id: string;
+    delegation_id: string;
+    name?: string;
+    is_active: boolean;
+    expires_at?: string;
+}
+export interface ListDelegatedOwnersResponse {
+    owners: DelegatedAgentOwner[];
+}
 export interface CreateDelegatedSessionRequest {
     ownerUserId: string;
+    /**
+     * Lowercase-hex (64 chars) ed25519 public key the agent generated for this
+     * delegated session. Required: subsequent requests acting on the owner's
+     * behalf are signed with the matching private key.
+     */
+    sessionPublicKey: string;
 }
 export interface CreateDelegatedSessionResponse {
-    access_token: string;
     expires_at: number;
     delegation_id: string;
     owner_user_id: string;
@@ -46,6 +61,7 @@ export interface CreateDelegatedSessionResponse {
 export interface DelegatedAgentsAPI extends BaseAPI {
     upsertDelegatedAgent(request: UpsertDelegatedAgentRequest): Promise<DelegatedAgent>;
     listDelegatedAgents(): Promise<ListDelegatedAgentsResponse>;
+    listDelegatedOwners(): Promise<ListDelegatedOwnersResponse>;
     revokeDelegatedAgent(delegatedAgentId: string): Promise<{
         status: "REVOKED";
     }>;