@metaflux-dex/client 0.0.3 → 0.0.5

package/src/client.ts

@@ -15,28 +15,114 @@ import {
   keccak256,
   recoverPubkey,
   signSecp256k1,
-} from './wasm.js';
-import { httpRequest } from './http.js';
+} from './wallet/wasm.js';
+import { httpRequest } from './rest/http.js';
 import {
+  buildNativeAgentSetAbstractionAction,
+  buildNativeApproveAgentAction,
+  buildNativeApproveBuilderFeeAction,
+  buildNativeBatchCancelAction,
+  buildNativeBatchModifyAction,
+  buildNativeBatchOrderAction,
   buildNativeCancelAction,
+  buildNativeCancelAllOrdersAction,
+  buildNativeCancelByCloidAction,
+  buildNativeClaimRewardsAction,
+  buildNativeConvertToMultiSigUserAction,
+  buildNativeCreateVaultAction,
+  buildNativeEarnDepositAction,
+  buildNativeEarnWithdrawAction,
+  buildNativeLinkStakingUserAction,
+  buildNativeMbWithdrawAction,
+  buildNativeModifyAction,
   buildNativeOrderAction,
+  buildNativePriorityBidAction,
+  buildNativeRegisterMetaliquidityOperatorAction,
+  buildNativeScheduleCancelAction,
+  buildNativeSetDisplayNameAction,
+  buildNativeSetMetaliquidityWhitelistAction,
+  buildNativeSetPositionModeAction,
+  buildNativeSetReferrerAction,
+  buildNativeSpotCancelAction,
+  buildNativeSpotMarginCloseAction,
+  buildNativeSpotMarginDepositAction,
+  buildNativeSpotMarginOpenAction,
+  buildNativeSpotMarginWithdrawAction,
+  buildNativeSpotOrderAction,
+  buildNativeSubmitEncryptedOrderAction,
+  buildNativeTokenDelegateAction,
+  buildNativeTopUpIsolatedOnlyMarginAction,
+  buildNativeTwapCancelAction,
+  buildNativeTwapOrderAction,
+  buildNativeUpdateIsolatedMarginAction,
+  buildNativeUpdateLeverageAction,
+  buildNativeUserDexAbstractionAction,
+  buildNativeUserPortfolioMarginAction,
+  buildNativeUserSetAbstractionAction,
+  buildNativeVaultModifyAction,
+  buildNativeVaultTransferAction,
+  buildNativeVaultWithdrawAction,
+} from './native/actions.js';
+import {
   nativeRequestBody,
   nextNonce,
   recoverNativeSigner,
   signNativeAction,
-} from './native.js';
-import { InfoApi } from './info.js';
-import { WsClient, type WsConfig } from './ws.js';
+} from './native/digest.js';
+import { InfoApi } from './rest/info.js';
+import { WsClient, type WsConfig } from './ws/ws.js';
 import type {
+  AgentSetAbstraction,
+  ApproveAgent,
+  ApproveBuilderFee,
+  BatchCancel,
+  BatchModify,
+  BatchOrder,
+  CancelAllOrders,
+  CancelByCloid,
+  ClaimRewards,
+  ConvertToMultiSigUser,
+  CreateVault,
+  LinkStakingUser,
   Market,
+  MbWithdraw,
+  Modify,
   NativeCancel,
+  NativeEarnDeposit,
+  NativeEarnWithdraw,
   NativeExchangeAck,
   NativeOrder,
+  NativeSetPositionMode,
+  NativeSpotCancel,
+  NativeSpotMarginClose,
+  NativeSpotMarginDeposit,
+  NativeSpotMarginOpen,
+  NativeSpotMarginWithdraw,
+  NativeSpotOrder,
   Order,
   OrderAck,
   Position,
+  PriorityBid,
+  RegisterMetaliquidityOperator,
+  ScheduleCancel,
+  SetDisplayName,
+  SetMetaliquidityWhitelist,
+  SetReferrer,
   SignedOrder,
-} from './types.js';
+  SubmitEncryptedOrder,
+  TokenDelegate,
+  TopUpIsolatedOnlyMargin,
+  TwapCancel,
+  TwapOrder,
+  UpdateIsolatedMargin,
+  UpdateLeverage,
+  UserDexAbstraction,
+  UserPortfolioMargin,
+  UserSetAbstraction,
+  VaultModify,
+  VaultTransfer,
+  VaultWithdraw,
+} from './types/index.js';
 
 /// Options accepted by the `Client` constructor.
 export interface ClientOpts {
@@ -53,10 +139,9 @@ export interface ClientOpts {
   chainId?: number;
 }
 
-/// Default chain ID for the EIP-712 domain. The MetaFlux mainnet ID is
-/// reserved-but-not-yet-assigned (PLAN.md §M.1 — "TBD pre-mainnet, avoid
-/// 999 which is HL"); the devnet default `31337` matches what the
-/// existing core-state tests use.
+/// Default chain ID for the EIP-712 domain. The devnet default `31337`
+/// matches the node's devnet configuration; production deployments
+/// override via `chainId`.
 const DEFAULT_CHAIN_ID = 31337;
 
 /// `keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")`
@@ -353,12 +438,525 @@ export class Client {
     });
   }
 
+  /// Toggle one-way / hedge position mode via `POST /exchange`.
+  ///
+  /// `setPositionMode({ hedge: true })` switches the account to hedge / two-way
+  /// mode; `{ hedge: false }` switches back to one-way / net. Same signed-action
+  /// envelope as the order paths, but SENDER-AUTHORIZED: the recovered signer IS
+  /// the account, so there is no `owner` to cross-check. The node only permits
+  /// the switch while the account is flat on every market (else it 4xxs).
+  ///
+  /// After switching to hedge mode, perp orders MUST carry `position_side`
+  /// (`"long"` / `"short"`); after switching back to one-way they MUST omit it.
+  async setPositionMode(
+    mode: NativeSetPositionMode,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSetPositionModeAction(mode),
+      opts,
+    );
+  }
+
+  /// Submit an SE-0 spot CLOB order via `POST /exchange`.
+  ///
+  /// v0 is IOC-limit only: `tif` defaults to `"ioc"` and `limit_px` must be
+  /// `> 0` (the builder + node both enforce it). Sender-authorized: the signer
+  /// is the trader, so there is no `owner` field and no local owner check.
+  async submitSpotOrderNative(
+    order: NativeSpotOrder,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeSpotOrderAction(order), opts);
+  }
+
+  /// Cancel a resting SE-0 spot order via `POST /exchange`.
+  ///
+  /// Cancels by `(pair, oid)`; the node cancels spot orders by `oid`. Sender-
+  /// authorized, same envelope as the other native actions.
+  async cancelSpotOrderNative(
+    cancel: NativeSpotCancel,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeSpotCancelAction(cancel), opts);
+  }
+
+  // ── spot margin & Earn actions (devnet preview) ───────────────────────────
+  //
+  // Leveraged spot borrows quote from the Earn lending pool. All SENDER-
+  // AUTHORIZED (the signer is the actor). Each returns the 202 admission ack,
+  // NOT a synchronous oid; observe committed state via `/info` `spot_margin_state`
+  // / `earn_state`. Preview: forced-liquidation settlement is not yet wired and
+  // per-pair maintenance ratios are still being calibrated.
+
+  /// Post quote collateral into a spot-margin account via `POST /exchange`.
+  /// Margin must be enabled for the pair (else the node rejects).
+  async spotMarginDeposit(
+    params: NativeSpotMarginDeposit,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSpotMarginDepositAction(params),
+      opts,
+    );
+  }
+
+  /// Withdraw free collateral from a spot-margin account via `POST /exchange`.
+  /// Full while flat; initial-margin-gated while a position is open.
+  async spotMarginWithdraw(
+    params: NativeSpotMarginWithdraw,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSpotMarginWithdrawAction(params),
+      opts,
+    );
+  }
+
+  /// Open a leveraged spot position via `POST /exchange`: borrow quote from the
+  /// pair's Earn pool and IOC-buy base. Gated by the initial-margin requirement.
+  async spotMarginOpen(
+    params: NativeSpotMarginOpen,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSpotMarginOpenAction(params),
+      opts,
+    );
+  }
+
+  /// Close a leveraged spot position via `POST /exchange`: IOC-sell the held
+  /// base, repay principal + interest, return the remainder (partial keeps open).
+  async spotMarginClose(
+    params: NativeSpotMarginClose,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSpotMarginCloseAction(params),
+      opts,
+    );
+  }
+
+  /// Supply quote into an Earn lending pool for shares via `POST /exchange`.
+  /// 1:1 on a fresh pool, else priced off NAV; the pool auto-creates.
+  async earnDeposit(
+    params: NativeEarnDeposit,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeEarnDepositAction(params), opts);
+  }
+
+  /// Redeem Earn pool shares back to quote via `POST /exchange`. The payout is
+  /// clamped to the pool's idle liquidity (`supplied − borrowed`).
+  async earnWithdraw(
+    params: NativeEarnWithdraw,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeEarnWithdrawAction(params),
+      opts,
+    );
+  }
+
+  // ── order management ──────────────────────────────
+
+  /// Cancel a resting order by its client order id via `POST /exchange`.
+  async cancelByCloid(
+    params: CancelByCloid,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeCancelByCloidAction(params), opts);
+  }
+
+  /// Amend a resting order's price and/or size in place via `POST /exchange`.
+  async modify(
+    params: Modify,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeModifyAction(params), opts);
+  }
+
+  /// Apply N modifications under one signature via `POST /exchange`.
+  async batchModify(
+    params: BatchModify,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeBatchModifyAction(params), opts);
+  }
+
+  /// Place N orders under one signature via `POST /exchange`. Each order's
+  /// `owner` must equal the signing wallet; the batch returns the admission
+  /// envelope (not per-order statuses).
+  async batchOrder(
+    batch: BatchOrder,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postBatchOwnerChecked(
+      buildNativeBatchOrderAction(batch),
+      batch.orders.map((o) => o.owner),
+      opts,
+    );
+  }
+
+  /// Apply N cancels under one signature via `POST /exchange`. Each cancel's
+  /// `owner` must equal the signing wallet.
+  async batchCancel(
+    batch: BatchCancel,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postBatchOwnerChecked(
+      buildNativeBatchCancelAction(batch),
+      batch.cancels.map((c) => c.owner),
+      opts,
+    );
+  }
+
+  /// Schedule a cancel-all of the sender's open orders at a future block.
+  async scheduleCancel(
+    params: ScheduleCancel,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeScheduleCancelAction(params), opts);
+  }
+
+  /// Cancel all of the sender's open orders (optionally one asset) via
+  /// `POST /exchange`.
+  async cancelAllOrders(
+    params: CancelAllOrders = {},
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeCancelAllOrdersAction(params), opts);
+  }
+
+  // ── TWAP ──────────────────────────────────────
+
+  /// Submit a sliced (TWAP) order via `POST /exchange`.
+  async twapOrder(
+    params: TwapOrder,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeTwapOrderAction(params), opts);
+  }
+
+  /// Cancel a running TWAP parent by id via `POST /exchange`.
+  async twapCancel(
+    params: TwapCancel,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeTwapCancelAction(params), opts);
+  }
+
+  // ── leverage & margin ──────────────────────────
+
+  /// Set per-asset leverage (and optionally flip to isolated) via `POST /exchange`.
+  async updateLeverage(
+    params: UpdateLeverage,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeUpdateLeverageAction(params), opts);
+  }
+
+  /// Add or remove isolated margin on an open position via `POST /exchange`.
+  async updateIsolatedMargin(
+    params: UpdateIsolatedMargin,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeUpdateIsolatedMarginAction(params),
+      opts,
+    );
+  }
+
+  /// Top up the margin of a strict-isolated-only position via `POST /exchange`.
+  async topUpIsolatedOnlyMargin(
+    params: TopUpIsolatedOnlyMargin,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeTopUpIsolatedOnlyMarginAction(params),
+      opts,
+    );
+  }
+
+  /// Enroll into or out of portfolio margin via `POST /exchange`.
+  async userPortfolioMargin(
+    params: UserPortfolioMargin,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeUserPortfolioMarginAction(params),
+      opts,
+    );
+  }
+
+  // ── account & agent settings ───────────────────
+
+  /// Set the account display name via `POST /exchange`.
+  async setDisplayName(
+    params: SetDisplayName,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeSetDisplayNameAction(params), opts);
+  }
+
+  /// Set the account referrer (one-time) via `POST /exchange`.
+  async setReferrer(
+    params: SetReferrer,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeSetReferrerAction(params), opts);
+  }
+
+  /// Approve an agent wallet to sign on this account's behalf via `POST /exchange`.
+  async approveAgent(
+    params: ApproveAgent,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeApproveAgentAction(params), opts);
+  }
+
+  /// Approve a builder fee ceiling (`max_bps`; `0` revokes) via `POST /exchange`.
+  async approveBuilderFee(
+    params: ApproveBuilderFee,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeApproveBuilderFeeAction(params),
+      opts,
+    );
+  }
+
+  /// Convert the account to an M-of-N multisig via `POST /exchange`.
+  async convertToMultiSigUser(
+    params: ConvertToMultiSigUser,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeConvertToMultiSigUserAction(params),
+      opts,
+    );
+  }
+
+  /// Toggle the account's DEX-abstraction opt-in flag via `POST /exchange`.
+  async userDexAbstraction(
+    params: UserDexAbstraction,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeUserDexAbstractionAction(params),
+      opts,
+    );
+  }
+
+  /// Set a self-scoped abstraction config value via `POST /exchange`.
+  async userSetAbstraction(
+    params: UserSetAbstraction,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeUserSetAbstractionAction(params),
+      opts,
+    );
+  }
+
+  /// As an approved agent, set an abstraction config value for `params.user`
+  /// via `POST /exchange`.
+  async agentSetAbstraction(
+    params: AgentSetAbstraction,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeAgentSetAbstractionAction(params),
+      opts,
+    );
+  }
+
+  /// Pay a priority fee (bps) for block-front placement via `POST /exchange`.
+  async priorityBid(
+    params: PriorityBid,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativePriorityBidAction(params), opts);
+  }
+
+  // ── staking ──────────────────────────────────
+
+  /// Delegate stake to a validator, or queue an undelegation, via `POST /exchange`.
+  async tokenDelegate(
+    params: TokenDelegate,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeTokenDelegateAction(params), opts);
+  }
+
+  /// Claim accrued staking rewards via `POST /exchange`.
+  async claimRewards(
+    params: ClaimRewards = {},
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeClaimRewardsAction(params), opts);
+  }
+
+  /// Alias another account as this account's staking target via `POST /exchange`.
+  async linkStakingUser(
+    params: LinkStakingUser,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeLinkStakingUserAction(params), opts);
+  }
+
+  // ── encrypted orders ───────────────────────────
+
+  /// Submit a threshold-encrypted order ciphertext via `POST /exchange`.
+  async submitEncryptedOrder(
+    params: SubmitEncryptedOrder,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSubmitEncryptedOrderAction(params),
+      opts,
+    );
+  }
+
+  // ── vaults ───────────────────────────────────
+
+  /// Create a new vault via `POST /exchange`. The signing wallet becomes the
+  /// leader. SENDER-AUTHORIZED.
+  async createVault(
+    params: CreateVault,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeCreateVaultAction(params), opts);
+  }
+
+  /// Leader moves capital into / out of a vault via `POST /exchange`.
+  async vaultTransfer(
+    params: VaultTransfer,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeVaultTransferAction(params), opts);
+  }
+
+  /// Leader updates vault configuration via `POST /exchange`.
+  async vaultModify(
+    params: VaultModify,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeVaultModifyAction(params), opts);
+  }
+
+  /// Follower redeems shares from a vault via `POST /exchange`. SENDER-AUTHORIZED.
+  async vaultWithdraw(
+    params: VaultWithdraw,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeVaultWithdrawAction(params), opts);
+  }
+
+  // ── MetaBridge ───────────────────────────────
+
+  /// Withdraw cross-collateral to a destination chain via `POST /exchange`.
+  async mbWithdraw(
+    params: MbWithdraw,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(buildNativeMbWithdrawAction(params), opts);
+  }
+
+  // ── governance / operator ─────────────────────
+
+  /// Set a metaliquidity-provider whitelist membership (validator-authorized)
+  /// via `POST /exchange`.
+  async setMetaliquidityWhitelist(
+    params: SetMetaliquidityWhitelist,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeSetMetaliquidityWhitelistAction(params),
+      opts,
+    );
+  }
+
+  /// Register or revoke an external strategy operator for a vault
+  /// (vault-leader-authorized) via `POST /exchange`.
+  async registerMetaliquidityOperator(
+    params: RegisterMetaliquidityOperator,
+    opts: { nonce?: bigint; chainId?: number } = {},
+  ): Promise<NativeExchangeAck> {
+    return this.postSenderAuthorized(
+      buildNativeRegisterMetaliquidityOperatorAction(params),
+      opts,
+    );
+  }
+
+  /// Sign a pre-built sender-authorized action JSON and POST it to `/exchange`.
+  ///
+  /// Shared by the actions where the recovered signer IS the actor (no `owner`
+  /// to cross-check): `set_position_mode`, `spot_order`, `spot_cancel`. Mirrors
+  /// `submitOrderNative`'s flow minus the owner-vs-signer guard.
+  private async postSenderAuthorized(
+    actionJson: string,
+    opts: { nonce?: bigint; chainId?: number },
+  ): Promise<NativeExchangeAck> {
+    if (this.privateKey === undefined) {
+      throw new Error(
+        'this action requires a privateKey in ClientOpts (this Client is read-only)',
+      );
+    }
+    const nonce = opts.nonce ?? nextNonce();
+    const signed = await signNativeAction(
+      this.privateKey,
+      actionJson,
+      nonce,
+      opts.chainId,
+    );
+    return httpRequest<NativeExchangeAck>(this.baseUrl, '/exchange', {
+      method: 'POST',
+      rawJson: nativeRequestBody(signed),
+      bearer: this.jwt,
+    });
+  }
+
+  /// Sign a pre-built batch action whose inner orders / cancels each carry an
+  /// `owner`, and POST it to `/exchange`. Recovers the signer once and rejects
+  /// unless EVERY inner `owner` equals it (the node sets the sender to the
+  /// recovered signer for all of them).
+  private async postBatchOwnerChecked(
+    actionJson: string,
+    owners: string[],
+    opts: { nonce?: bigint; chainId?: number },
+  ): Promise<NativeExchangeAck> {
+    if (this.privateKey === undefined) {
+      throw new Error(
+        'this action requires a privateKey in ClientOpts (this Client is read-only)',
+      );
+    }
+    const nonce = opts.nonce ?? nextNonce();
+    const signed = await signNativeAction(
+      this.privateKey,
+      actionJson,
+      nonce,
+      opts.chainId,
+    );
+    const signer = await recoverNativeSigner(signed, opts.chainId);
+    for (const owner of owners) {
+      if (signer.toLowerCase() !== owner.toLowerCase()) {
+        throw new Error(`batch item owner ${owner} != recovered signer ${signer}`);
+      }
+    }
+    return httpRequest<NativeExchangeAck>(this.baseUrl, '/exchange', {
+      method: 'POST',
+      rawJson: nativeRequestBody(signed),
+      bearer: this.jwt,
+    });
+  }
+
   /// Open an MTF-native WebSocket connection to `<baseUrl>/ws`.
   ///
   /// Derives the `ws(s)://` URL from the client's `http(s)://` base, mounts the
   /// `/ws` path (the node's upgrade route), and returns a connected
   /// [`WsClient`]. Register handlers via `ws.onMessage` and subscribe with
-  /// `ws.subscribe({ type: 'l2Book', coin: 'BTC' })`.
+  /// `ws.subscribe({ type: 'l2_book', coin: 'BTC' })`.
   async connectWs(config: Partial<WsConfig> = {}): Promise<WsClient> {
     const ws = new WsClient(httpToWsUrl(this.baseUrl), config);
     await ws.connect();
@@ -401,7 +999,7 @@ export class Client {
 /// Encode a `Uint8Array` as a base64url string (no padding).
 ///
 /// Matches the encoding the gateway's `LoginEnvelope.signature` field
-/// expects (see `metaflux/crates/api-gateway/src/ccxt/auth.rs`). We
+/// expects. We
 /// avoid Buffer/global polyfills here because the SDK targets both
 /// node and the browser; manual base64 is small and avoids the
 /// dependency.

package/src/faucet.ts

@@ -11,7 +11,7 @@
 // synchronously. Devnet / testnet only — mainnet refuses (surfaced as a
 // `MetaFluxApiError`).
 
-import { httpRequest } from './http.js';
+import { httpRequest } from './rest/http.js';
 
 /// Successful faucet response (200). `status` is `"queued"` — the credit is
 /// staged for the next block, so the balance updates after ~1 block rather