@0xmonaco/types 0.8.8 → 0.8.11

package/README.md

@@ -22,7 +22,7 @@ import { MonacoSDK, SDKConfig } from "@0xmonaco/types";
 // SDK configuration
 interface SDKConfig {
   walletClient?: WalletClient; // Wallet client for signing operations
-  network: Network; // Network preset: "local", "development", "staging", or "mainnet"
+  network: Network; // Use "staging" for public testnet or "mainnet" for production
   seiRpcUrl: string; // RPC URL for Sei blockchain interactions
 }
 
@@ -293,7 +293,7 @@ Types for network configuration:
 ```typescript
 import { Network, NetworkEndpoints } from "@0xmonaco/types";
 
-type Network = "mainnet" | "development" | "staging" | "local";
+const publicNetwork: Network = "staging";
 
 interface NetworkEndpoints {
   rpcUrl: string;
@@ -301,13 +301,15 @@ interface NetworkEndpoints {
 }
 ```
 
+For public integrations, use `"staging"` or `"mainnet"`.
+
 ## Type Reference
 
 ### SDK Types
 
 - `MonacoSDK`: Main SDK interface with all API modules
 - `SDKConfig`: Configuration options for the Monaco SDK
-- `Network`: Network type ("mainnet" | "development" | "staging" | "local")
+- `Network`: SDK network preset type. Public integrations should use `"staging"` or `"mainnet"`.
 - `AuthState`: Authentication state information
 
 ### Vault Types

package/dist/api/index.d.ts

@@ -16,4 +16,11 @@ export interface BaseAPI {
      * @param credentials - Hex-encoded session keypair, or `undefined` to clear.
      */
     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/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,15 +1,15 @@
 /**
  * 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, SessionCredentials, SessionRefreshResponse } 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 {
     /**
@@ -57,12 +57,6 @@ export interface AuthAPI extends BaseAPI {
      * @returns Promise resolving to the authentication state
      */
     verifySignature(address: string, signature: string, nonce: string, clientId: string, session: SessionCredentials): Promise<AuthState>;
-    /**
-     * Authenticates a backend service using a secret key.
-     * @param secretKey - Secret key of the application
-     * @returns Promise resolving to the backend auth response
-     */
-    authenticateBackend(secretKey: string): Promise<BackendAuthResponse>;
     /**
      * Extends the current session's expiry. The request is signed with the
      * active session key (set via {@link setSessionKeypair}).
@@ -82,4 +76,4 @@ export interface AuthAPI extends BaseAPI {
      */
     setWalletClient(walletClient: unknown): void;
 }
-export type { ApplicationInfo, AuthState, BackendAuthResponse, ChallengeResponse, SessionCredentials, SessionRefreshResponse, 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

@@ -51,17 +51,6 @@ export interface ApplicationInfo {
     /** 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;
-}
 /**
  * A session keypair, hex-encoded. The private key is used to sign requests;
  * the public key identifies the session server-side.

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";
     }>;

package/dist/faucet/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Faucet Types
+ *
+ * Types for the testnet token faucet. Wire shapes are snake_case.
+ *
+ * NOTE: The faucet is **testnet-only** and performs real on-chain mints from a
+ * backend-operator-funded signer. It is disabled (returns an error) if the
+ * gateway operator has not configured a signer; the SDK caller has no control
+ * over that. It is rate-limited per user (default 1 request / 24h).
+ */
+import type { BaseAPI } from "../api";
+/** A token successfully minted by the faucet. */
+export interface MintedToken {
+    /** Asset UUID */
+    asset_id: string;
+    /** Token symbol */
+    symbol: string;
+    /** Amount minted in token units */
+    amount: string;
+    /** On-chain transaction hash */
+    tx_hash: string;
+}
+/** A token the faucet failed to mint. */
+export interface FailedMint {
+    /** Asset UUID */
+    asset_id: string;
+    /** Token symbol */
+    symbol: string;
+    /** Error message describing why the mint failed */
+    error: string;
+}
+/** Result of a faucet mint request. */
+export interface MintTokensResponse {
+    /** Tokens that were successfully minted */
+    minted: MintedToken[];
+    /** Tokens that failed to mint */
+    failed: FailedMint[];
+    /** Remaining faucet requests in the next 24h */
+    remaining_requests_24h: number;
+}
+/**
+ * Faucet API interface. Session-authenticated.
+ */
+export interface FaucetAPI extends BaseAPI {
+    /**
+     * Mints the full set of testnet tokens to the authenticated user.
+     *
+     * Testnet-only and rate-limited; see the module note. Partial success is
+     * possible — inspect `minted` and `failed` in the response.
+     *
+     * @returns Promise resolving to the minted/failed tokens and remaining quota
+     */
+    mint(): Promise<MintTokensResponse>;
+}

package/dist/faucet/index.js

@@ -0,0 +1,10 @@
+/**
+ * Faucet Types
+ *
+ * Types for the testnet token faucet. Wire shapes are snake_case.
+ *
+ * NOTE: The faucet is **testnet-only** and performs real on-chain mints from a
+ * backend-operator-funded signer. It is disabled (returns an error) if the
+ * gateway operator has not configured a signer; the SDK caller has no control
+ * over that. It is rate-limited per user (default 1 request / 24h).
+ */

package/dist/index.d.ts

@@ -9,13 +9,17 @@ export * from "./applications";
 export * from "./auth";
 export * from "./contracts";
 export * from "./delegated-agents";
+export * from "./faucet";
 export * from "./fees";
 export * from "./margin-accounts";
 export * from "./market";
 export * from "./positions";
 export * from "./profile";
 export * from "./sdk";
+export * from "./sub-accounts";
 export * from "./trading";
 export * from "./validation";
 export * from "./vault";
 export * from "./websocket";
+export * from "./whitelist";
+export * from "./withdrawals";

package/dist/index.js

@@ -10,13 +10,17 @@ export * from "./applications";
 export * from "./auth";
 export * from "./contracts";
 export * from "./delegated-agents";
+export * from "./faucet";
 export * from "./fees";
 export * from "./margin-accounts";
 export * from "./market";
 export * from "./positions";
 export * from "./profile";
 export * from "./sdk";
+export * from "./sub-accounts";
 export * from "./trading";
 export * from "./validation";
 export * from "./vault";
 export * from "./websocket";
+export * from "./whitelist";
+export * from "./withdrawals";