@0xmonaco/core 0.8.7 → 0.8.10

package/dist/api/whitelist/api.js

@@ -0,0 +1,32 @@
+/**
+ * Whitelist API Implementation
+ *
+ * Public (unauthenticated) whitelist/waitlist application submission. The
+ * server validates and de-duplicates by wallet address and email, creating an
+ * inactive user pending manual approval. This is an onboarding endpoint, not a
+ * trading operation.
+ *
+ * @example
+ * ```typescript
+ * const { message, user_id } = await sdk.whitelist.submit({
+ *   wallet_address: "0x...",
+ *   email: "user@example.com",
+ * });
+ * ```
+ */
+import { BaseAPI } from "../base";
+import { perpRoutes } from "../perp/routes";
+export class WhitelistAPIImpl extends BaseAPI {
+    /**
+     * Submits a whitelist (waitlist) application. Public — no auth required.
+     *
+     * @param body - Applicant details
+     * @returns Promise resolving to the status message and created user id
+     */
+    async submit(body) {
+        return await this.makePublicRequest(perpRoutes.whitelist.submit(), {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+}

package/dist/api/whitelist/index.d.ts

@@ -0,0 +1 @@
+export { WhitelistAPIImpl } from "./api";

package/dist/api/whitelist/index.js

@@ -0,0 +1 @@
+export { WhitelistAPIImpl } from "./api";

package/dist/api/withdrawals/api.d.ts

@@ -0,0 +1,15 @@
+import type { InitiateWithdrawalRequest, WithdrawalResponse, WithdrawalsAPI } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+/**
+ * Low-level withdrawals client.
+ *
+ * `initiateWithdrawal` debits the caller's balance via the matching engine and
+ * returns the target vault address plus pre-signed `executeSignedWithdrawal`
+ * calldata; `getWithdrawal` re-fetches that calldata for a previously-initiated
+ * index. Neither submits on-chain — use the high-level vault API for the flow
+ * that also broadcasts the transaction.
+ */
+export declare class WithdrawalsAPIImpl extends BaseAPI implements WithdrawalsAPI {
+    initiateWithdrawal(request: InitiateWithdrawalRequest): Promise<WithdrawalResponse>;
+    getWithdrawal(withdrawalIndex: number): Promise<WithdrawalResponse>;
+}

package/dist/api/withdrawals/api.js

@@ -0,0 +1,27 @@
+import { BaseAPI } from "../base";
+import { perpRoutes } from "../perp";
+/**
+ * Low-level withdrawals client.
+ *
+ * `initiateWithdrawal` debits the caller's balance via the matching engine and
+ * returns the target vault address plus pre-signed `executeSignedWithdrawal`
+ * calldata; `getWithdrawal` re-fetches that calldata for a previously-initiated
+ * index. Neither submits on-chain — use the high-level vault API for the flow
+ * that also broadcasts the transaction.
+ */
+export class WithdrawalsAPIImpl extends BaseAPI {
+    async initiateWithdrawal(request) {
+        return this.makeAuthenticatedRequest(perpRoutes.withdrawals.initiate(), {
+            method: "POST",
+            body: JSON.stringify({
+                asset_id: request.assetId,
+                amount: request.amount,
+                destination: request.destination,
+            }),
+        });
+    }
+    async getWithdrawal(withdrawalIndex) {
+        // Public lookup — no auth required.
+        return this.makePublicRequest(perpRoutes.withdrawals.byIndex(withdrawalIndex));
+    }
+}

package/dist/api/withdrawals/index.d.ts

@@ -0,0 +1 @@
+export * from "./api";

package/dist/api/withdrawals/index.js

@@ -0,0 +1 @@
+export * from "./api";

package/dist/coverage.d.ts

@@ -0,0 +1,85 @@
+/** operationId → the @0xmonaco/core client method that covers it. */
+export declare const COVERED: {
+    add_position_margin: string;
+    attach_position_tp_sl: string;
+    batch_cancel_all: string;
+    batch_cancel_all_by_pair: string;
+    batch_cancel_orders: string;
+    batch_create_orders: string;
+    batch_replace_orders: string;
+    cancel_conditional_order: string;
+    cancel_order: string;
+    close_position: string;
+    create_challenge: string;
+    create_delegated_session: string;
+    create_order: string;
+    create_sub_account_limit: string;
+    delete_sub_account_limit: string;
+    get_application_config: string;
+    get_application_stats: string;
+    get_available_collateral: string;
+    get_candles: string;
+    get_funding_state: string;
+    get_index_price: string;
+    get_margin_account_movements: string;
+    get_margin_account_summary: string;
+    get_mark_price: string;
+    get_market_metadata: string;
+    get_open_interest: string;
+    get_order_by_id: string;
+    get_orderbook_snapshot: string;
+    get_orders: string;
+    get_perp_market_config: string;
+    get_perp_market_summary: string;
+    get_portfolio_chart: string;
+    get_portfolio_stats: string;
+    get_position: string;
+    get_position_risk: string;
+    get_screener: string;
+    get_sub_account_limits: string;
+    get_trade_by_id: string;
+    get_trades: string;
+    get_trading_pair_by_id: string;
+    get_user_balance_by_asset: string;
+    get_user_balances: string;
+    get_user_movements: string;
+    get_user_profile: string;
+    get_user_trades: string;
+    get_withdrawal: string;
+    initiate_withdrawal: string;
+    list_application_balances: string;
+    list_application_movements: string;
+    list_application_orders: string;
+    list_application_users: string;
+    list_conditional_orders: string;
+    list_delegated_agent_owners: string;
+    list_delegated_agents: string;
+    list_funding_history: string;
+    list_funding_payments: string;
+    list_margin_accounts: string;
+    list_position_history: string;
+    list_positions: string;
+    list_sub_accounts_with_balances: string;
+    list_trading_pairs: string;
+    mint_tokens: string;
+    reduce_position_margin: string;
+    refresh_session: string;
+    replace_order: string;
+    revoke_delegated_agent: string;
+    revoke_session: string;
+    simulate_auto_margin_order_risk: string;
+    simulate_fees: string;
+    simulate_order_risk: string;
+    submit_whitelist: string;
+    transfer_collateral_from_margin_account: string;
+    transfer_collateral_to_auto_margin_account: string;
+    transfer_collateral_to_margin_account: string;
+    update_sub_account_limit: string;
+    upsert_delegated_agent: string;
+    verify_signature: string;
+};
+/** operationId → reason it is intentionally not covered by @0xmonaco/core. */
+export declare const INTENTIONALLY_EXCLUDED: {
+    authenticate_backend: string;
+    health_check: string;
+};

package/dist/coverage.js

@@ -0,0 +1,85 @@
+/** operationId → the @0xmonaco/core client method that covers it. */
+export const COVERED = {
+    add_position_margin: "addPositionMargin",
+    attach_position_tp_sl: "attachPositionTpSl",
+    batch_cancel_all: "batchCancelAll",
+    batch_cancel_all_by_pair: "batchCancelAll (with tradingPairId)",
+    batch_cancel_orders: "batchCancel",
+    batch_create_orders: "batchCreate",
+    batch_replace_orders: "batchReplace",
+    cancel_conditional_order: "cancelConditionalOrder",
+    cancel_order: "cancelOrder",
+    close_position: "closePosition",
+    create_challenge: "createChallenge",
+    create_delegated_session: "createDelegatedSession",
+    create_order: "placeLimitOrder / placeMarketOrder",
+    create_sub_account_limit: "subAccounts.createLimit",
+    delete_sub_account_limit: "subAccounts.deleteLimit",
+    get_application_config: "getApplicationConfig",
+    get_application_stats: "getApplicationStats",
+    get_available_collateral: "getAvailableCollateral",
+    get_candles: "getCandlesticks",
+    get_funding_state: "getFundingState",
+    get_index_price: "getIndexPrice",
+    get_margin_account_movements: "getMarginAccountMovements",
+    get_margin_account_summary: "getMarginAccountSummary",
+    get_mark_price: "getMarkPrice",
+    get_market_metadata: "getMarketMetadata",
+    get_open_interest: "getOpenInterest",
+    get_order_by_id: "getOrder",
+    get_orderbook_snapshot: "getOrderbook",
+    get_orders: "getPaginatedOrders",
+    get_perp_market_config: "getPerpMarketConfig",
+    get_perp_market_summary: "getPerpMarketSummary",
+    get_portfolio_chart: "getPortfolioChart",
+    get_portfolio_stats: "getPortfolioStats",
+    get_position: "getPosition",
+    get_position_risk: "getPositionRisk",
+    get_screener: "getScreener",
+    get_sub_account_limits: "subAccounts.getLimits",
+    get_trade_by_id: "getTradeById",
+    get_trades: "getTrades",
+    get_trading_pair_by_id: "getTradingPair",
+    get_user_balance_by_asset: "getUserBalanceByAssetId",
+    get_user_balances: "getUserBalances",
+    get_user_movements: "getPaginatedUserMovements",
+    get_user_profile: "getProfile",
+    get_user_trades: "getUserTrades",
+    get_withdrawal: "getWithdrawal",
+    initiate_withdrawal: "initiateWithdrawal",
+    list_application_balances: "listApplicationBalances",
+    list_application_movements: "listApplicationMovements",
+    list_application_orders: "listApplicationOrders",
+    list_application_users: "listApplicationUsers",
+    list_conditional_orders: "listConditionalOrders",
+    list_delegated_agent_owners: "listDelegatedOwners",
+    list_delegated_agents: "listDelegatedAgents",
+    list_funding_history: "listFundingHistory",
+    list_funding_payments: "listFundingPayments",
+    list_margin_accounts: "listMarginAccounts",
+    list_position_history: "listPositionHistory",
+    list_positions: "listPositions",
+    list_sub_accounts_with_balances: "subAccounts.list",
+    list_trading_pairs: "getPaginatedTradingPairs",
+    mint_tokens: "faucet.mint",
+    reduce_position_margin: "reducePositionMargin",
+    refresh_session: "refreshSession",
+    replace_order: "replaceOrder",
+    revoke_delegated_agent: "revokeDelegatedAgent",
+    revoke_session: "revokeSession",
+    simulate_auto_margin_order_risk: "simulateAutoMarginOrderRisk",
+    simulate_fees: "simulateFees",
+    simulate_order_risk: "simulateOrderRisk",
+    submit_whitelist: "whitelist.submit",
+    transfer_collateral_from_margin_account: "transferCollateralFromMarginAccount",
+    transfer_collateral_to_auto_margin_account: "transferCollateralToAutoMarginAccount",
+    transfer_collateral_to_margin_account: "transferCollateralToMarginAccount",
+    update_sub_account_limit: "subAccounts.updateLimit",
+    upsert_delegated_agent: "upsertDelegatedAgent",
+    verify_signature: "verifySignature",
+};
+/** operationId → reason it is intentionally not covered by @0xmonaco/core. */
+export const INTENTIONALLY_EXCLUDED = {
+    authenticate_backend: "Backend auth is header-based via setServerKey()/the x-server-key header, not an endpoint method (MON-1486).",
+    health_check: "Infrastructure liveness probe (GET /health); not part of the data SDK surface.",
+};

package/dist/crypto/session.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Session keypair crypto for noncustodial request signing.
+ *
+ * On login the SDK generates a random ed25519 keypair locally. The public key
+ * is registered with the server (bound by the wallet's signature on the
+ * challenge); every subsequent authenticated request is signed with the
+ * private key. The server verifies the signature against the stored public
+ * key — it never sees the private key, so it cannot mint requests as the user.
+ */
+/** A locally-generated ed25519 session keypair (raw 32-byte values). */
+export interface SessionKeypair {
+    /** 32-byte ed25519 public key */
+    publicKey: Uint8Array;
+    /** 32-byte ed25519 private key (seed) */
+    privateKey: Uint8Array;
+}
+/**
+ * Generate a fresh ed25519 session keypair.
+ *
+ * `@noble/curves` sources entropy from `crypto.getRandomValues`. Environments
+ * without it (very old Node without webcrypto, locked-down sandboxes) will
+ * throw — we surface a clear error rather than producing a weak key.
+ */
+export declare function generateSessionKeypair(): SessionKeypair;
+export declare function publicKeyHex(keypair: SessionKeypair): string;
+export declare function privateKeyHex(keypair: SessionKeypair): string;
+/** Reconstruct a keypair from its hex-encoded halves (e.g. restored from storage). */
+export declare function keypairFromHex(publicKeyHex: string, privateKeyHex: string): SessionKeypair;
+/** Lowercase-hex sha256 of the given bytes. Use over an empty array for no-body requests. */
+export declare function sha256Hex(data: Uint8Array): string;
+/**
+ * Canonical per-request signing string. Mirrors the server
+ * (`handlers::auth::compose_signing_string`):
+ * `METHOD\nPATH_WITH_QUERY\nTIMESTAMP_MS\nSHA256_BODY_HEX`.
+ */
+export declare function composeSigningString(method: string, pathWithQuery: string, timestampMs: number, bodySha256Hex: string): string;
+/** Canonical WebSocket handshake signing string: `WS-AUTH\n<pubkey-hex>\n<ts>`. */
+export declare function composeWsSigningString(publicKeyHex: string, timestampMs: number): string;
+/** Sign an arbitrary string with the session private key, returning lowercase hex. */
+export declare function signMessage(privateKey: Uint8Array, message: string): string;

package/dist/crypto/session.js

@@ -0,0 +1,60 @@
+/**
+ * Session keypair crypto for noncustodial request signing.
+ *
+ * On login the SDK generates a random ed25519 keypair locally. The public key
+ * is registered with the server (bound by the wallet's signature on the
+ * challenge); every subsequent authenticated request is signed with the
+ * private key. The server verifies the signature against the stored public
+ * key — it never sees the private key, so it cannot mint requests as the user.
+ */
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils";
+/**
+ * Generate a fresh ed25519 session keypair.
+ *
+ * `@noble/curves` sources entropy from `crypto.getRandomValues`. Environments
+ * without it (very old Node without webcrypto, locked-down sandboxes) will
+ * throw — we surface a clear error rather than producing a weak key.
+ */
+export function generateSessionKeypair() {
+    if (typeof globalThis.crypto?.getRandomValues !== "function") {
+        throw new Error("Secure randomness (crypto.getRandomValues) is unavailable; cannot generate a session keypair.");
+    }
+    const privateKey = ed25519.utils.randomPrivateKey();
+    const publicKey = ed25519.getPublicKey(privateKey);
+    return { publicKey, privateKey };
+}
+export function publicKeyHex(keypair) {
+    return bytesToHex(keypair.publicKey);
+}
+export function privateKeyHex(keypair) {
+    return bytesToHex(keypair.privateKey);
+}
+/** Reconstruct a keypair from its hex-encoded halves (e.g. restored from storage). */
+export function keypairFromHex(publicKeyHex, privateKeyHex) {
+    return {
+        publicKey: hexToBytes(publicKeyHex),
+        privateKey: hexToBytes(privateKeyHex),
+    };
+}
+/** Lowercase-hex sha256 of the given bytes. Use over an empty array for no-body requests. */
+export function sha256Hex(data) {
+    return bytesToHex(sha256(data));
+}
+/**
+ * Canonical per-request signing string. Mirrors the server
+ * (`handlers::auth::compose_signing_string`):
+ * `METHOD\nPATH_WITH_QUERY\nTIMESTAMP_MS\nSHA256_BODY_HEX`.
+ */
+export function composeSigningString(method, pathWithQuery, timestampMs, bodySha256Hex) {
+    return `${method.toUpperCase()}\n${pathWithQuery}\n${timestampMs}\n${bodySha256Hex}`;
+}
+/** Canonical WebSocket handshake signing string: `WS-AUTH\n<pubkey-hex>\n<ts>`. */
+export function composeWsSigningString(publicKeyHex, timestampMs) {
+    return `WS-AUTH\n${publicKeyHex}\n${timestampMs}`;
+}
+/** Sign an arbitrary string with the session private key, returning lowercase hex. */
+export function signMessage(privateKey, message) {
+    return bytesToHex(ed25519.sign(utf8ToBytes(message), privateKey));
+}

package/dist/sdk.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationsAPI, AuthAPI, AuthState, DelegatedAgentsAPI, FeesAPI, MarginAccountsAPI, MarketAPI, MonacoSDK, Network, PositionsAPI, ProfileAPI, SDKConfig, TradingAPI, VaultAPI } from "@0xmonaco/types";
+import type { ApplicationsAPI, AuthAPI, AuthState, DelegatedAgentsAPI, FaucetAPI, FeesAPI, MarginAccountsAPI, MarketAPI, MonacoSDK, Network, PositionsAPI, ProfileAPI, SDKConfig, SubAccountsAPI, TradingAPI, VaultAPI, WhitelistAPI, WithdrawalsAPI } from "@0xmonaco/types";
 import { type PublicClient, type TransactionReceipt, type WalletClient } from "viem";
 import { type MonacoWebSocket, OrderbookAPIImpl, TradesAPIImpl } from "./api";
 export declare class MonacoSDKImpl implements MonacoSDK {
@@ -7,10 +7,14 @@ export declare class MonacoSDKImpl implements MonacoSDK {
     applications: ApplicationsAPI;
     fees: FeesAPI;
     vault: VaultAPI;
+    withdrawals: WithdrawalsAPI;
     trading: TradingAPI;
     market: MarketAPI;
     marginAccounts: MarginAccountsAPI;
     positions: PositionsAPI;
+    subAccounts: SubAccountsAPI;
+    faucet: FaucetAPI;
+    whitelist: WhitelistAPI;
     profile: ProfileAPI;
     orderbook: OrderbookAPIImpl;
     trades: TradesAPIImpl;
@@ -21,21 +25,44 @@ export declare class MonacoSDKImpl implements MonacoSDK {
     private readonly network;
     private readonly chain;
     /**
-     * Propagate the access token to all APIs and WebSocket
+     * Propagate the session keypair (or `undefined` to clear) to all APIs and
+     * the WebSocket client.
      */
-    private propagateAccessToken;
+    private propagateSession;
+    /**
+     * Set (or clear) the application secret key used for backend-authenticated
+     * requests (those annotated `#[require_backend]` on the gateway, e.g. the
+     * `applications` reporting endpoints).
+     *
+     * The raw `sk_...` key is sent in the `x-server-key` header on each such
+     * request. This is independent of {@link login}/session auth — a client may
+     * hold both a session and a server key at once.
+     *
+     * @param serverKey - The application secret key (`sk_...`), or `undefined` to clear.
+     *
+     * @example
+     * ```typescript
+     * sdk.setServerKey("sk_live_...");
+     * const orders = await sdk.applications.listApplicationOrders({ status: "FILLED" });
+     * ```
+     */
+    setServerKey(serverKey: string | undefined): void;
+    /** Extract the session keypair from an auth state. */
+    private sessionFromAuthState;
     constructor(cfg: SDKConfig);
     /**
      * Authenticate the user
      *
-     * Returns an AuthState object containing:
-     * - `accessToken`: For making authenticated API requests
-     * - `refreshToken`: For refreshing tokens AND revoking (logout)
-     * - `expiresAt`: When the access token expires
+     * Generates a session keypair, has the wallet authorize it, and returns an
+     * AuthState object containing:
+     * - `sessionPublicKey` / `sessionPrivateKey`: the session keypair used to
+     *   sign subsequent requests (the private key is the credential — persist it
+     *   to survive reloads without re-prompting the wallet)
+     * - `expiresAt`: When the session expires
      * - `user`: User information
      *
-     * Note: Use `sdk.logout()` to revoke the token and clean up, or call
-     * `sdk.auth.revokeToken()` directly to just revoke.
+     * Note: Use `sdk.logout()` to revoke the session and clean up, or call
+     * `sdk.auth.revokeSession()` directly to just revoke.
      *
      * @param clientId - The client ID for authentication
      * @param options - Optional configuration
@@ -49,18 +76,24 @@ export declare class MonacoSDKImpl implements MonacoSDK {
      * // Login and auto-connect WebSocket
      * const authState = await sdk.login(clientId, { connectWebSocket: true });
      *
-     * // Manual WebSocket connection
-     * await sdk.ws.connect();
-     *
      * // Later, to revoke:
-     * await sdk.auth.revokeToken(); // ✅
+     * await sdk.auth.revokeSession(); // ✅
      * // Or revoke and disconnect WebSocket:
-     * await sdk.logout(); // ✅ Calls revokeToken internally and disconnects WebSocket
+     * await sdk.logout(); // ✅ Calls revokeSession internally and disconnects WebSocket
      * ```
      */
     login(clientId: string, options?: {
         connectWebSocket?: boolean;
     }): Promise<AuthState>;
+    /**
+     * Create and adopt an owner-scoped delegated session.
+     *
+     * This must be called while authenticated as the agent wallet. The delegated
+     * session uses a fresh ed25519 keypair generated locally; the current agent
+     * session signs the registration request, and subsequent SDK calls use the
+     * delegated session keypair.
+     */
+    loginAsDelegatedOwner(ownerUserId: string): Promise<AuthState>;
     /**
      * Get the current authentication state
      *
@@ -77,19 +110,24 @@ export declare class MonacoSDKImpl implements MonacoSDK {
     /**
      * Log the user out
      *
-     * This method revokes the refresh token (if available), disconnects all authenticated
+     * This method revokes the session (if authenticated), disconnects all authenticated
      * WebSocket channels, and clears the local auth state.
-     * It internally calls `auth.revokeToken()` to invalidate the token on the server.
+     * It internally calls `auth.revokeSession()` to invalidate the session on the server.
      *
      * @example
      * ```typescript
      * await sdk.logout();
-     * // Token is revoked, authenticated WebSockets disconnected, and local state cleared
+     * // Session is revoked, authenticated WebSockets disconnected, and local state cleared
      * ```
      */
     logout(): Promise<void>;
     /**
-     * Refresh the access token
+     * Refresh the current session, extending its expiry.
+     *
+     * Signs a refresh request with the active session key and updates the local
+     * `expiresAt`. The session keypair is unchanged. If no session is active, or
+     * the session has expired/been revoked, this throws.
+     *
      * @returns The updated authentication state
      */
     refreshAuth(): Promise<AuthState>;