@metaflux-dex/client 0.0.2 → 0.0.3

package/dist/faucet.d.ts

@@ -0,0 +1,8 @@
+export interface FaucetResponse {
+    address: string;
+    usdc: number;
+    mtf: number;
+    status: string;
+}
+export declare function requestFaucet(faucetBaseUrl: string, address: string, amount?: number): Promise<FaucetResponse>;
+//# sourceMappingURL=faucet.d.ts.map

package/dist/faucet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faucet.d.ts","sourceRoot":"","sources":["../src/faucet.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,cAAc;IAE7B,OAAO,EAAE,MAAM,CAAC;IAEhB,IAAI,EAAE,MAAM,CAAC;IAEb,GAAG,EAAE,MAAM,CAAC;IAEZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAkBD,wBAAsB,aAAa,CACjC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CASzB"}

package/dist/faucet.js

@@ -0,0 +1,40 @@
+// Devnet / testnet faucet helper.
+//
+// The node exposes a faucet at `POST <faucetBaseUrl>/faucet` that credits an
+// address with test USDC + MTF. It runs on its OWN origin (devnet node port 8080;
+// production `https://faucet.devnet.mtf.exchange`), SEPARATE from the trading
+// API base URL — so `requestFaucet` takes a dedicated `faucetBaseUrl` rather
+// than reusing a `Client`'s trading base URL.
+//
+// The grant is staged for the NEXT block: a 200 response carries
+// `status: "queued"` and the credited balance lands after ~1 block, not
+// synchronously. Devnet / testnet only — mainnet refuses (surfaced as a
+// `MetaFluxApiError`).
+import { httpRequest } from './http.js';
+/// Request test USDC from a devnet / testnet faucet.
+///
+/// POSTs `{ address, amount? }` to `<faucetBaseUrl>/faucet` (grants both USDC and MTF). `amount` is a
+/// whole-USDC integer; omit it for the faucet's full default grant (capped
+/// server-side).
+///
+/// `faucetBaseUrl` is the faucet's OWN origin (e.g. `http://localhost:8080`
+/// on devnet, `https://faucet.devnet.mtf.exchange` in production) — NOT the
+/// trading API base URL.
+///
+/// On success the credit is `"queued"` for the next block; the balance updates
+/// after ~1 block, not synchronously.
+///
+/// Throws `MetaFluxApiError` on a non-2xx status, surfacing the server's
+/// `{ error }` message — notably 429 (rate-limited: per-address once-ever, per-IP
+/// 1/minute), 400 (bad/zero address), 503 (backlog full), or a mainnet refusal.
+export async function requestFaucet(faucetBaseUrl, address, amount) {
+    const json = { address };
+    if (amount !== undefined) {
+        json.amount = amount;
+    }
+    return httpRequest(faucetBaseUrl, '/faucet', {
+        method: 'POST',
+        json,
+    });
+}
+//# sourceMappingURL=faucet.js.map

package/dist/faucet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"faucet.js","sourceRoot":"","sources":["../src/faucet.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,6EAA6E;AAC7E,kFAAkF;AAClF,8EAA8E;AAC9E,6EAA6E;AAC7E,8CAA8C;AAC9C,EAAE;AACF,iEAAiE;AACjE,wEAAwE;AACxE,wEAAwE;AACxE,uBAAuB;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAgBxC,qDAAqD;AACrD,GAAG;AACH,sGAAsG;AACtG,2EAA2E;AAC3E,iBAAiB;AACjB,GAAG;AACH,4EAA4E;AAC5E,4EAA4E;AAC5E,yBAAyB;AACzB,GAAG;AACH,+EAA+E;AAC/E,sCAAsC;AACtC,GAAG;AACH,yEAAyE;AACzE,kFAAkF;AAClF,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,aAAqB,EACrB,OAAe,EACf,MAAe;IAEf,MAAM,IAAI,GAAyC,EAAE,OAAO,EAAE,CAAC;IAC/D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IACD,OAAO,WAAW,CAAiB,aAAa,EAAE,SAAS,EAAE;QAC3D,MAAM,EAAE,MAAM;QACd,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { Client, type ClientOpts } from './client.js';
 export { MetaFluxApiError } from './http.js';
+export { requestFaucet, type FaucetResponse } from './faucet.js';
 export { MTF_CHAIN_ID, MTF_MAINNET_CHAIN_ID, MTF_TESTNET_CHAIN_ID, nativeActionDigest, buildNativeOrderAction, buildNativeCancelAction, signNativeAction, recoverNativeSigner, nativeRequestBody, } from './native.js';
 export { InfoApi, type AccountRef, } from './info.js';
 export type { NodeInfo, AccountState, AccountPosition, Balances, Tier, MarginMode, MarketInfo, Funding, VaultState, StakingState, Delegation, PendingUnstake, FeeSchedule, FeeTier, OpenOrders, OpenOrder, L2Book, L2Level, RecentTrades, UserFills, FundingHistory, FundingSample, BlockInfo, Agents, AgentEntry, SubAccounts, SubAccountEntry, Mip3ActiveBids, Mip3Bid, SpotMeta, SpotPair, SpotClearinghouseState, SpotBalance, ExchangeStatus, FrontendOpenOrders, FrontendOpenOrder, OrderTrigger, Liquidatable, LiquidatableAccount, ActiveAssetData, MaxMarketOrderNtls, MaxMarketOrderNtl, VaultSummaries, VaultSummary, UserVaultEquities, VaultEquity, LeadingVaults, UserRateLimit, SpotDeployState, DelegatorSummary, MaxBuilderFee, UserToMultiSigSigners, UserRole, PerpsAtOpenInterestCap, ValidatorL1Votes, ValidatorL1Vote, MarginTable, MarginTier, PerpDexs, PerpDex, ValidatorSummaries, ValidatorSummary, GossipRootIps, WebData2, WebData2Clearinghouse, WebData2Position, } from './info-types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAGL,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,OAAO,EACP,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,YAAY,EAKV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,UAAU,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,UAAU,EACV,SAAS,EACT,MAAM,EACN,OAAO,EACP,YAAY,EACZ,SAAS,EACT,cAAc,EACd,aAAa,EACb,SAAS,EACT,MAAM,EACN,UAAU,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,OAAO,EAEP,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,QAAQ,EACR,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,QAAQ,EACR,WAAW,EACX,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,QAAQ,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,iBAAiB,EACjB,aAAa,EAIb,SAAS,EACT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,KAAK,EACL,OAAO,EACP,WAAW,EACX,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,GAAG,EACH,aAAa,EAEb,WAAW,EACX,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EACf,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAGL,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,OAAO,EACP,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,YAAY,EAKV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,UAAU,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,UAAU,EACV,SAAS,EACT,MAAM,EACN,OAAO,EACP,YAAY,EACZ,SAAS,EACT,cAAc,EACd,aAAa,EACb,SAAS,EACT,MAAM,EACN,UAAU,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,OAAO,EAEP,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,QAAQ,EACR,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,QAAQ,EACR,WAAW,EACX,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,QAAQ,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,iBAAiB,EACjB,aAAa,EAIb,SAAS,EACT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,KAAK,EACL,OAAO,EACP,WAAW,EACX,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,GAAG,EACH,aAAa,EAEb,WAAW,EACX,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EACf,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -8,6 +8,7 @@
 //     import { Client, type Order } from '@metaflux-dex/client';
 export { Client } from './client.js';
 export { MetaFluxApiError } from './http.js';
+export { requestFaucet } from './faucet.js';
 export { 
 // MTF-native signed-action surface (the path the server now accepts).
 // Exported so power users can build / sign / inspect actions out-of-band.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,uCAAuC;AACvC,EAAE;AACF,iEAAiE;AAEjE,OAAO,EAAE,MAAM,EAAmB,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO;AACL,sEAAsE;AACtE,0EAA0E;AAC1E,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO;AACL,8EAA8E;AAC9E,OAAO,GAER,MAAM,WAAW,CAAC;AA0EnB,OAAO;AACL,4DAA4D;AAC5D,QAAQ,EACR,WAAW,GAMZ,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,iBAAiB,EACjB,aAAa;AACb,gEAAgE;AAChE,+DAA+D;AAC/D,wCAAwC;AACxC,SAAS,EACT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,uCAAuC;AACvC,EAAE;AACF,iEAAiE;AAEjE,OAAO,EAAE,MAAM,EAAmB,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAuB,MAAM,aAAa,CAAC;AACjE,OAAO;AACL,sEAAsE;AACtE,0EAA0E;AAC1E,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO;AACL,8EAA8E;AAC9E,OAAO,GAER,MAAM,WAAW,CAAC;AA0EnB,OAAO;AACL,4DAA4D;AAC5D,QAAQ,EACR,WAAW,GAMZ,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,iBAAiB,EACjB,aAAa;AACb,gEAAgE;AAChE,+DAA+D;AAC/D,wCAAwC;AACxC,SAAS,EACT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaflux-dex/client",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "MetaFlux (MTF) TypeScript client SDK — WASM-backed crypto + ESM-only fetch wrappers.",
   "type": "module",
   "author": "MetaFlux",

package/src/faucet.ts

@@ -0,0 +1,59 @@
+// Devnet / testnet faucet helper.
+//
+// The node exposes a faucet at `POST <faucetBaseUrl>/faucet` that credits an
+// address with test USDC + MTF. It runs on its OWN origin (devnet node port 8080;
+// production `https://faucet.devnet.mtf.exchange`), SEPARATE from the trading
+// API base URL — so `requestFaucet` takes a dedicated `faucetBaseUrl` rather
+// than reusing a `Client`'s trading base URL.
+//
+// The grant is staged for the NEXT block: a 200 response carries
+// `status: "queued"` and the credited balance lands after ~1 block, not
+// synchronously. Devnet / testnet only — mainnet refuses (surfaced as a
+// `MetaFluxApiError`).
+
+import { httpRequest } from './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
+/// than synchronously.
+export interface FaucetResponse {
+  /// Echo of the credited address (`0x`-prefixed 20-byte hex).
+  address: string;
+  /// Whole-USDC cross-collateral granted (capped server-side, default 3000).
+  usdc: number;
+  /// MTF spot tokens granted (fixed, default 10).
+  mtf: number;
+  /// Always `"queued"` — credit staged for the next block.
+  status: string;
+}
+
+/// Request test USDC from a devnet / testnet faucet.
+///
+/// POSTs `{ address, amount? }` to `<faucetBaseUrl>/faucet` (grants both USDC and MTF). `amount` is a
+/// whole-USDC integer; omit it for the faucet's full default grant (capped
+/// server-side).
+///
+/// `faucetBaseUrl` is the faucet's OWN origin (e.g. `http://localhost:8080`
+/// on devnet, `https://faucet.devnet.mtf.exchange` in production) — NOT the
+/// trading API base URL.
+///
+/// On success the credit is `"queued"` for the next block; the balance updates
+/// after ~1 block, not synchronously.
+///
+/// Throws `MetaFluxApiError` on a non-2xx status, surfacing the server's
+/// `{ error }` message — notably 429 (rate-limited: per-address once-ever, per-IP
+/// 1/minute), 400 (bad/zero address), 503 (backlog full), or a mainnet refusal.
+export async function requestFaucet(
+  faucetBaseUrl: string,
+  address: string,
+  amount?: number,
+): Promise<FaucetResponse> {
+  const json: { address: string; amount?: number } = { address };
+  if (amount !== undefined) {
+    json.amount = amount;
+  }
+  return httpRequest<FaucetResponse>(faucetBaseUrl, '/faucet', {
+    method: 'POST',
+    json,
+  });
+}

package/src/index.ts

@@ -9,6 +9,7 @@
 
 export { Client, type ClientOpts } from './client.js';
 export { MetaFluxApiError } from './http.js';
+export { requestFaucet, type FaucetResponse } from './faucet.js';
 export {
   // MTF-native signed-action surface (the path the server now accepts).
   // Exported so power users can build / sign / inspect actions out-of-band.