@interchained/usdx 0.1.0

package/LICENSE

@@ -0,0 +1,352 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are talking about freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or other options, such
+as a menu, a program that is not interactive in that case does not need
+to display this notice.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that is
+widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally applicable free
+software which is unspecified components of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your legal rights or third parties' legal rights to forbid
+circumvention of technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice and
+disclaimer of warranty; keep intact all notices stating that this
+License and any non-warranty terms added in accord with section 7
+apply to the code; keep intact all notices of the absence of any
+warranty; and give all recipients a copy of this License along with
+the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for
+    anyone who comes into possession of a copy of the covered work
+    (for binary distributions under subsection 6b), or who received
+    the covered work for a price (for source distributions).
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the public at no charge
+    under subsection 6d.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+  Copyright (C) Interchained Contributors
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -0,0 +1,379 @@
+
+<p align="center">
+  <img src="https://img.shields.io/badge/%40interchained%2Fusdx-TypeScript%20SDK-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="@interchained/usdx"/>
+</p>
+
+<h1 align="center">💠 @interchained/usdx</h1>
+
+<p align="center">
+  <strong>Typed TypeScript HTTP client for the USDx wallet API.</strong><br/>
+  Zero production dependencies. Runs everywhere. Strict by default.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@interchained/usdx"><img src="https://img.shields.io/npm/v/@interchained/usdx?color=CB3837&style=flat-square&logo=npm&logoColor=white" alt="npm version"/></a>
+  <img src="https://img.shields.io/badge/node-18%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node 18+"/>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript strict"/>
+  <img src="https://img.shields.io/badge/deps-zero-brightgreen?style=flat-square" alt="Zero deps"/>
+  <img src="https://img.shields.io/badge/runtime-Node%20%7C%20Browser%20%7C%20Deno%20%7C%20Bun-black?style=flat-square" alt="Universal runtime"/>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3-blue?style=flat-square" alt="License: GPLv3"/></a>
+</p>
+
+---
+
+## ⚡ The Lore
+
+> *USDx is the stable settlement currency of the Interchained network — the financial bloodstream that connects creators, node operators, traders, and builders.*
+>
+> *On the server, [`interchained-usdx`](https://github.com/interchained/usdx-py) guards every balance with atomic Lua scripts running inside Redis. No locks. No races. No double-spends.*
+>
+> *This package is the client side of that contract — a zero-dependency TypeScript SDK that speaks fluent HTTP to any server built on the Python package. Fully typed. Strict. Runs in every JavaScript runtime that ships native `fetch`.*
+>
+> *Whether you're building a Next.js dashboard, a React Native wallet, or a serverless Cloudflare Worker — this is how you talk to USDx.*
+
+---
+
+## 📦 Install
+
+```bash
+# npm
+npm install @interchained/usdx
+
+# pnpm
+pnpm add @interchained/usdx
+
+# yarn
+yarn add @interchained/usdx
+
+# bun
+bun add @interchained/usdx
+```
+
+---
+
+## 🏗️ How it fits together
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Your TypeScript / Next.js / React Native / Cloudflare app   │
+│                                                              │
+│    import { USDxClient } from "@interchained/usdx"           │
+│                                                              │
+│    ✓ zero production deps     ✓ native fetch                 │
+│    ✓ strict TypeScript        ✓ Node • Browser • Deno • Bun  │
+└──────────────────────┬───────────────────────────────────────┘
+                       │  HTTP / REST
+                       │  (JSON, standard HTTP status codes)
+┌──────────────────────▼───────────────────────────────────────┐
+│  FastAPI wallet server  (interchained-usdx Python package)   │
+│                                                              │
+│    from usdx import USDxWallet, NowPaymentsService, …        │
+│                                                              │
+│    ✓ Lua atomic scripts    ✓ NowPayments IPN handler         │
+│    ✓ PSBT payout builder   ✓ OTC rate engine                 │
+└──────────────────────┬───────────────────────────────────────┘
+                       │
+               ┌───────▼────────┐
+               │   Redis 6+     │
+               │ (the source    │
+               │  of truth)     │
+               └────────────────┘
+```
+
+---
+
+## 🚀 Quick start
+
+```ts
+import { USDxClient } from "@interchained/usdx";
+
+const client = new USDxClient({
+  baseUrl:   "https://api.yourapp.com",
+  apiKey:    "your-api-key",    // optional — sent as X-Api-Key
+  timeoutMs: 10_000,
+});
+
+// ── Balance ───────────────────────────────────────────────────
+const { balance } = await client.getBalance("alice");
+console.log(balance);                  // 20.74
+
+const info = await client.getInfo("alice");
+console.log(info.is_frozen);           // false
+console.log(info.total_credited);      // 50.00
+
+const history = await client.getHistory("alice", { limit: 10 });
+// → Transaction[]
+
+// ── Credit / Debit ────────────────────────────────────────────
+const tx = await client.credit({
+  userId:      "alice",
+  amount:      10.00,
+  description: "Article view earnings",
+  txType:      "view_reward",
+  multiplier:  1.5,    // 1.5× for premium — applied atomically server-side
+});
+console.log(tx.amount);          // 15.0
+console.log(tx.balance_after);   // 35.74
+
+// Both InsufficientBalance and AccountFrozen are first-class error types
+try {
+  await client.debit({ userId: "alice", amount: 3.99, description: "Subscription" });
+} catch (e) {
+  if (e instanceof InsufficientBalance) console.log("Not enough funds");
+  if (e instanceof AccountFrozen)       console.log("Account is locked");
+}
+
+// ── Transfer ──────────────────────────────────────────────────
+const { debit, credit } = await client.transfer({
+  fromUser:    "alice",
+  toUser:      "bob",
+  amount:      5.00,
+  description: "Tip",
+});
+console.log(debit.balance_after, credit.balance_after);
+
+// ── Freeze / Unfreeze (fraud protection) ─────────────────────
+await client.freeze("alice");
+await client.unfreeze("alice");
+
+// ── NowPayments crypto deposits ───────────────────────────────
+const invoice = await client.createDeposit({
+  userId:   "alice",
+  amount:   25.00,
+  currency: "usdttrc20",    // any of 22 supported coins
+});
+console.log(invoice.payment_url);    // Redirect user here ↗
+
+const status = await client.checkPayment("payment_id_here");
+console.log(status.status);          // "waiting" | "confirming" | "finished" | "failed"
+
+const result = await client.claimPayment("payment_id_here");
+// result.already_processed === true if already claimed (idempotent)
+
+// ── OTC rate engine ───────────────────────────────────────────
+const rate  = await client.getOtcRate();   // ITC per 1 USDx (e.g. 10.5)
+const stats = await client.getOtcStats();  // { itc_reserve, usdx_supply, current_rate, … }
+```
+
+---
+
+## 📚 Full API reference
+
+### `new USDxClient(options)`
+
+```ts
+new USDxClient({
+  baseUrl:   string,                         // required — your wallet server URL
+  apiKey?:   string,                         // sent as X-Api-Key header
+  headers?:  Record<string, string>,         // merged into every request
+  timeoutMs?: number,                        // default: 30_000 ms
+  fetch?:    typeof fetch,                   // swap in a polyfill or test mock
+})
+```
+
+---
+
+### Balance operations
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getBalance` | `(userId: string)` | `Promise<{ user_id: string; balance: number }>` |
+| `getInfo` | `(userId: string)` | `Promise<BalanceInfo>` |
+| `getHistory` | `(userId: string, opts?: { limit?, offset? })` | `Promise<Transaction[]>` |
+| `credit` | `(opts: CreditOptions)` | `Promise<Transaction>` |
+| `debit` | `(opts: DebitOptions)` | `Promise<Transaction>` |
+| `transfer` | `(opts: TransferOptions)` | `Promise<TransferResult>` |
+| `freeze` | `(userId: string)` | `Promise<void>` |
+| `unfreeze` | `(userId: string)` | `Promise<void>` |
+
+### Deposits
+
+| Method | Signature | Returns |
+|---|---|---|
+| `createDeposit` | `(opts: DepositOptions)` | `Promise<DepositInvoice>` |
+| `checkPayment` | `(paymentId: string)` | `Promise<PaymentStatus>` |
+| `claimPayment` | `(paymentId: string)` | `Promise<ClaimResult>` |
+
+### OTC rate engine
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getOtcRate` | `()` | `Promise<number>` |
+| `getOtcStats` | `()` | `Promise<OtcStats>` |
+
+---
+
+## 🔷 TypeScript types
+
+All types are exported from the package root. Import only what you need.
+
+```ts
+import type {
+  // Core wallet
+  Transaction,
+  BalanceInfo,
+  TransferResult,
+
+  // Deposits
+  DepositInvoice,
+  PaymentStatus,
+  ClaimResult,
+
+  // OTC
+  OtcStats,
+
+  // Request option shapes
+  CreditOptions,
+  DebitOptions,
+  TransferOptions,
+  DepositOptions,
+} from "@interchained/usdx";
+```
+
+### Key type shapes
+
+```ts
+interface Transaction {
+  id:            string;
+  user_id:       string;
+  direction:     "credit" | "debit";
+  tx_type:       string;
+  amount:        number;
+  balance_after: number;
+  description:   string;
+  metadata:      Record<string, unknown> | null;
+  created_at:    string;   // ISO 8601
+}
+
+interface BalanceInfo {
+  user_id:        string;
+  balance:        number;
+  total_credited: number;
+  total_debited:  number;
+  is_frozen:      boolean;
+  created_at:     string | null;
+  last_updated:   string | null;
+}
+```
+
+---
+
+## 🚨 Error handling
+
+All SDK errors extend `USDxError`. Each is a concrete class you can `instanceof` against.
+
+```ts
+import { USDxError, InsufficientBalance, AccountFrozen, HttpError } from "@interchained/usdx";
+
+try {
+  await client.debit({ userId: "alice", amount: 999_999, description: "YOLO" });
+} catch (e) {
+  if (e instanceof InsufficientBalance) {
+    // HTTP 422 — balance too low
+    console.log("Not enough funds:", e.message);
+  }
+  else if (e instanceof AccountFrozen) {
+    // HTTP 403 — account is locked by fraud protection
+    console.log("Account locked:", e.message);
+  }
+  else if (e instanceof HttpError) {
+    // Any other non-2xx response
+    console.log(`HTTP ${e.statusCode}:`, e.message);
+  }
+  else if (e instanceof USDxError) {
+    // Network timeout, DNS failure, etc.
+    console.log("SDK error:", e.message);
+  }
+}
+```
+
+---
+
+## 🔬 Bring your own `fetch`
+
+The client accepts a custom `fetch` function — useful for testing, polyfilling, or logging every request.
+
+```ts
+// ── Test mocking ──────────────────────────────────────────────
+const client = new USDxClient({
+  baseUrl: "http://localhost:8000",
+  fetch: async (url, init) => {
+    // intercept, inspect, or stub any request
+    return mockFetch(url, init);
+  },
+});
+
+// ── Node.js < 18 polyfill ────────────────────────────────────
+import nodeFetch from "node-fetch";
+const client = new USDxClient({ baseUrl: "...", fetch: nodeFetch as typeof fetch });
+
+// ── Request logging middleware ────────────────────────────────
+const client = new USDxClient({
+  baseUrl: "...",
+  fetch: async (url, init) => {
+    console.log("→", init?.method, url);
+    const res = await fetch(url, init);
+    console.log("←", res.status);
+    return res;
+  },
+});
+```
+
+---
+
+## 📁 Examples
+
+See [`examples/`](examples/) for runnable code:
+
+| Example | Description |
+|---|---|
+| [`quickstart.ts`](examples/quickstart.ts) | End-to-end Node.js script covering every `USDxClient` method |
+| [`express-wallet-app/`](examples/express-wallet-app/) | Express skeleton that uses `USDxClient` as a proxy layer — add your auth, validation, and business logic on top |
+
+---
+
+## 🔨 Building from source
+
+```bash
+npm install
+npm run build     # compiles to dist/ (ESM .js + .d.ts)
+npm run check     # tsc --noEmit (strict, zero warnings)
+```
+
+---
+
+## 🐍 Server-side companion
+
+This SDK is the client half of the USDx stack. The server half is built with the Python package:
+
+```bash
+pip install interchained-usdx
+```
+
+See [`interchained-usdx` on PyPI](https://pypi.org/project/interchained-usdx/) and the
+[`usdx-py` repo](https://github.com/interchained/usdx-py) for the full wallet engine, NowPayments IPN handler, PSBT builder, and OTC rate engine.
+
+---
+
+## 🤝 Contributing
+
+1. Fork → branch → make your changes
+2. `npm run check` — zero TypeScript errors
+3. `npm run build` — clean build with no new `.js` artifacts committed
+4. Open a PR with a clear description of what changed and why
+
+Please report security issues via private message, not public issues.
+
+---
+
+## 📜 License
+
+GNU General Public License v3.0 or later.
+See [LICENSE](LICENSE) for the full text.
+
+```
+@interchained/usdx  Copyright (C) 2024  Interchained
+This program comes with ABSOLUTELY NO WARRANTY.
+This is free software, and you are welcome to redistribute it
+under the terms of the GPLv3.
+```

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * USDxClient — typed HTTP SDK for the USDx wallet API.
+ *
+ * Works in Node.js 18+, browsers, Deno, and Bun (any runtime with
+ * native `fetch`).  Pass a custom `fetch` in options to support older
+ * environments or for test mocking.
+ *
+ * Usage:
+ *   import { USDxClient } from "@interchained/usdx";
+ *   const client = new USDxClient("https://api.yourapp.com");
+ *   const balance = await client.getBalance("alice");
+ */
+import type { BalanceInfo, ClaimResult, CreditOptions, DebitOptions, DepositInvoice, OtcStats, PaymentStatus, Transaction, TransferOptions, TransferResult, USDxClientOptions } from "./types.js";
+export declare class USDxClient {
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    private readonly _fetch;
+    constructor(baseUrl: string, options?: USDxClientOptions);
+    /** Return the current USDx balance for a user (0 if account is new). */
+    getBalance(userId: string): Promise<number>;
+    /** Return full account state for a user. */
+    getInfo(userId: string): Promise<BalanceInfo>;
+    /** Return the most recent transactions for a user, newest first. */
+    getHistory(userId: string, limit?: number): Promise<Transaction[]>;
+    /**
+     * Credit (add) USDx to a user's account.
+     *
+     * @param multiplier - Pass `1.5` for premium users; server default is `1.0`.
+     */
+    credit(userId: string, amount: number, options?: CreditOptions): Promise<Transaction>;
+    /**
+     * Debit (subtract) USDx from a user's account.
+     *
+     * @throws {InsufficientBalance} if the balance is too low.
+     * @throws {AccountFrozen} if the account has been frozen.
+     */
+    debit(userId: string, amount: number, options?: DebitOptions): Promise<Transaction>;
+    /**
+     * Atomically transfer USDx from one user to another.
+     *
+     * @throws {InsufficientBalance} if `fromId` doesn't have enough balance.
+     * @throws {AccountFrozen} if `fromId`'s account is frozen.
+     */
+    transfer(fromId: string, toId: string, amount: number, options?: TransferOptions): Promise<TransferResult>;
+    /** Freeze an account — blocks all future debits and transfers out. */
+    freeze(userId: string): Promise<void>;
+    /** Lift a freeze on an account. */
+    unfreeze(userId: string): Promise<void>;
+    /**
+     * Create a NowPayments hosted invoice for a crypto deposit.
+     *
+     * @param currency - NowPayments currency code, e.g. `"usdttrc20"`, `"btc"`, `"eth"`.
+     */
+    createDeposit(userId: string, amount: number, currency?: string): Promise<DepositInvoice>;
+    /** Check the current status of a NowPayments payment. */
+    checkPayment(paymentId: string): Promise<PaymentStatus>;
+    /**
+     * Claim a completed payment — idempotent, safe to call multiple times.
+     * Returns `already_processed: true` if the payment was claimed before.
+     */
+    claimPayment(paymentId: string): Promise<ClaimResult>;
+    /** Return the current ITC-per-USDx exchange rate. */
+    getOtcRate(): Promise<number>;
+    /** Return full OTC pool statistics. */
+    getOtcStats(): Promise<OtcStats>;
+    private _get;
+    private _post;
+    private _request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,aAAa,EACb,WAAW,EACX,eAAe,EACf,cAAc,EACd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB;IAe5D,wEAAwE;IAClE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjD,4CAA4C;IACtC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAMnD,oEAAoE;IAC9D,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAMpE;;;;OAIG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC;IAQvB;;;;;OAKG;IACG,KAAK,CACT,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC;IAQvB;;;;;OAKG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC;IAS1B,sEAAsE;IAChE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,mCAAmC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C;;;;OAIG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,SAAc,GACrB,OAAO,CAAC,cAAc,CAAC;IAQ1B,yDAAyD;IACnD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAM7D;;;OAGG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAU3D,qDAAqD;IAC/C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAKnC,uCAAuC;IACjC,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;YAQxB,IAAI;YAIJ,KAAK;YAIL,QAAQ;CA8CvB"}

package/dist/client.js

@@ -0,0 +1,174 @@
+/**
+ * USDxClient — typed HTTP SDK for the USDx wallet API.
+ *
+ * Works in Node.js 18+, browsers, Deno, and Bun (any runtime with
+ * native `fetch`).  Pass a custom `fetch` in options to support older
+ * environments or for test mocking.
+ *
+ * Usage:
+ *   import { USDxClient } from "@interchained/usdx";
+ *   const client = new USDxClient("https://api.yourapp.com");
+ *   const balance = await client.getBalance("alice");
+ */
+import { AccountFrozen, HttpError, InsufficientBalance, USDxError, } from "./errors.js";
+export class USDxClient {
+    constructor(baseUrl, options = {}) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this._fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.defaultHeaders = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...(options.apiKey ? { "X-Api-Key": options.apiKey } : {}),
+            ...options.headers,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Balance operations
+    // ---------------------------------------------------------------------------
+    /** Return the current USDx balance for a user (0 if account is new). */
+    async getBalance(userId) {
+        const data = await this._get(`/balance/${encodeURIComponent(userId)}`);
+        return data.balance;
+    }
+    /** Return full account state for a user. */
+    async getInfo(userId) {
+        return this._get(`/balance/${encodeURIComponent(userId)}/info`);
+    }
+    /** Return the most recent transactions for a user, newest first. */
+    async getHistory(userId, limit = 50) {
+        return this._get(`/balance/${encodeURIComponent(userId)}/history?limit=${limit}`);
+    }
+    /**
+     * Credit (add) USDx to a user's account.
+     *
+     * @param multiplier - Pass `1.5` for premium users; server default is `1.0`.
+     */
+    async credit(userId, amount, options = {}) {
+        return this._post("/wallet/credit", {
+            user_id: userId,
+            amount,
+            ...options,
+        });
+    }
+    /**
+     * Debit (subtract) USDx from a user's account.
+     *
+     * @throws {InsufficientBalance} if the balance is too low.
+     * @throws {AccountFrozen} if the account has been frozen.
+     */
+    async debit(userId, amount, options = {}) {
+        return this._post("/wallet/debit", {
+            user_id: userId,
+            amount,
+            ...options,
+        });
+    }
+    /**
+     * Atomically transfer USDx from one user to another.
+     *
+     * @throws {InsufficientBalance} if `fromId` doesn't have enough balance.
+     * @throws {AccountFrozen} if `fromId`'s account is frozen.
+     */
+    async transfer(fromId, toId, amount, options = {}) {
+        return this._post("/wallet/transfer", {
+            from_id: fromId,
+            to_id: toId,
+            amount,
+            ...options,
+        });
+    }
+    /** Freeze an account — blocks all future debits and transfers out. */
+    async freeze(userId) {
+        await this._post("/wallet/freeze", { user_id: userId });
+    }
+    /** Lift a freeze on an account. */
+    async unfreeze(userId) {
+        await this._post("/wallet/unfreeze", { user_id: userId });
+    }
+    // ---------------------------------------------------------------------------
+    // NowPayments deposits
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a NowPayments hosted invoice for a crypto deposit.
+     *
+     * @param currency - NowPayments currency code, e.g. `"usdttrc20"`, `"btc"`, `"eth"`.
+     */
+    async createDeposit(userId, amount, currency = "usdttrc20") {
+        return this._post("/deposit/create", {
+            user_id: userId,
+            amount,
+            currency,
+        });
+    }
+    /** Check the current status of a NowPayments payment. */
+    async checkPayment(paymentId) {
+        return this._get(`/payment/${encodeURIComponent(paymentId)}`);
+    }
+    /**
+     * Claim a completed payment — idempotent, safe to call multiple times.
+     * Returns `already_processed: true` if the payment was claimed before.
+     */
+    async claimPayment(paymentId) {
+        return this._post(`/payment/${encodeURIComponent(paymentId)}/claim`);
+    }
+    // ---------------------------------------------------------------------------
+    // OTC rate engine
+    // ---------------------------------------------------------------------------
+    /** Return the current ITC-per-USDx exchange rate. */
+    async getOtcRate() {
+        const data = await this._get("/otc/rate");
+        return data.rate;
+    }
+    /** Return full OTC pool statistics. */
+    async getOtcStats() {
+        return this._get("/otc/stats");
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    async _get(path) {
+        return this._request("GET", path);
+    }
+    async _post(path, body) {
+        return this._request("POST", path, body);
+    }
+    async _request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const init = {
+            method,
+            headers: this.defaultHeaders,
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        let res;
+        try {
+            res = await this._fetch(url, init);
+        }
+        catch (err) {
+            throw new USDxError(`Network error reaching USDx server: ${err.message}`);
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let message = text;
+            try {
+                const parsed = JSON.parse(text);
+                message =
+                    String(parsed.detail ?? parsed.message ?? parsed.error ?? text);
+            }
+            catch {
+                // use raw text
+            }
+            const lower = message.toLowerCase();
+            if (lower.includes("insufficient") || lower.includes("balance")) {
+                throw new InsufficientBalance(message);
+            }
+            if (lower.includes("frozen")) {
+                throw new AccountFrozen(message);
+            }
+            throw new HttpError(res.status, message);
+        }
+        return res.json();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Typed error hierarchy for the USDx SDK.
+ *
+ * All errors thrown by USDxClient are subclasses of USDxError so you can
+ * catch the entire family with a single `catch (e) { if (e instanceof USDxError) … }`.
+ */
+export declare class USDxError extends Error {
+    constructor(message: string);
+}
+/** The account doesn't have enough balance for the requested debit / transfer. */
+export declare class InsufficientBalance extends USDxError {
+    constructor(message?: string);
+}
+/** The account is frozen — all outgoing operations are blocked. */
+export declare class AccountFrozen extends USDxError {
+    constructor(message?: string);
+}
+/** The USDx server returned an unexpected HTTP error. */
+export declare class HttpError extends USDxError {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAK5B;AAED,kFAAkF;AAClF,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAA+B;CAKnD;AAED,mEAAmE;AACnE,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAuB;CAK3C;AAED,yDAAyD;AACzD,qBAAa,SAAU,SAAQ,SAAS;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMhD"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+/**
+ * Typed error hierarchy for the USDx SDK.
+ *
+ * All errors thrown by USDxClient are subclasses of USDxError so you can
+ * catch the entire family with a single `catch (e) { if (e instanceof USDxError) … }`.
+ */
+export class USDxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "USDxError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The account doesn't have enough balance for the requested debit / transfer. */
+export class InsufficientBalance extends USDxError {
+    constructor(message = "Insufficient USDx balance.") {
+        super(message);
+        this.name = "InsufficientBalance";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The account is frozen — all outgoing operations are blocked. */
+export class AccountFrozen extends USDxError {
+    constructor(message = "Account is frozen.") {
+        super(message);
+        this.name = "AccountFrozen";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The USDx server returned an unexpected HTTP error. */
+export class HttpError extends USDxError {
+    constructor(statusCode, message) {
+        super(`HTTP ${statusCode}: ${message}`);
+        this.name = "HttpError";
+        this.statusCode = statusCode;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD,YAAY,OAAO,GAAG,4BAA4B;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,SAAU,SAAQ,SAAS;IAGtC,YAAY,UAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,QAAQ,UAAU,KAAK,OAAO,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @interchained/usdx
+ *
+ * Typed HTTP client SDK for the USDx wallet API.
+ * Pairs with the `interchained-usdx` Python server library.
+ */
+export { USDxClient } from "./client.js";
+export { AccountFrozen, HttpError, InsufficientBalance, USDxError, } from "./errors.js";
+export type { BalanceInfo, ClaimResult, CreditOptions, DebitOptions, DepositInvoice, OtcStats, PaymentStatus, Transaction, TransferOptions, TransferResult, USDxClientOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,aAAa,EACb,WAAW,EACX,eAAe,EACf,cAAc,EACd,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @interchained/usdx
+ *
+ * Typed HTTP client SDK for the USDx wallet API.
+ * Pairs with the `interchained-usdx` Python server library.
+ */
+export { USDxClient } from "./client.js";
+export { AccountFrozen, HttpError, InsufficientBalance, USDxError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,SAAS,GACV,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Core data models — mirrors the Python usdx-py package.
+ */
+export interface Transaction {
+    id: string;
+    user_id: string;
+    /** e.g. "credit", "debit", "transfer_in", "transfer_out", "deposit", "withdrawal" */
+    type: string;
+    amount: number;
+    balance_after: number;
+    description: string;
+    created_at: string;
+    reference_id?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface BalanceInfo {
+    user_id: string;
+    balance: number;
+    total_credited: number;
+    total_debited: number;
+    is_frozen: boolean;
+    created_at?: string | null;
+    last_updated?: string | null;
+}
+export interface TransferResult {
+    debit_tx: Transaction;
+    credit_tx: Transaction;
+}
+export interface DepositInvoice {
+    success: boolean;
+    invoice_id: string;
+    token_id?: string | null;
+    payment_url?: string | null;
+    pay_address?: string | null;
+    pay_amount?: number | null;
+    pay_currency: string;
+    order_id: string;
+    created_at?: string | null;
+}
+export interface PaymentStatus {
+    success: boolean;
+    status: string;
+    pay_amount?: number | null;
+    actually_paid?: number | null;
+    price_amount?: number | null;
+    price_currency?: string | null;
+    pay_currency?: string | null;
+    order_id?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+export interface ClaimResult {
+    success: boolean;
+    username?: string;
+    amount?: number;
+    currency?: string;
+    payment_id?: string;
+    error?: string;
+    already_processed?: boolean;
+}
+export interface OtcStats {
+    itc_reserve: number;
+    usdx_supply: number;
+    adjustment_factor: number;
+    current_rate: number;
+    paused: boolean;
+    timestamp: string;
+}
+export interface CreditOptions {
+    description?: string;
+    tx_type?: string;
+    reference_id?: string;
+    metadata?: Record<string, unknown>;
+    /** Premium multiplier, e.g. 1.5 for premium users. Server-side default: 1.0 */
+    multiplier?: number;
+}
+export interface DebitOptions {
+    description?: string;
+    tx_type?: string;
+    reference_id?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TransferOptions {
+    description?: string;
+    reference_id?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface USDxClientOptions {
+    /** API key sent as `X-Api-Key` header. */
+    apiKey?: string;
+    /** Any additional headers to include in every request. */
+    headers?: Record<string, string>;
+    /**
+     * Custom fetch implementation.  Defaults to the global `fetch`.
+     * Useful for test mocking or environments without native fetch.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core data models — mirrors the Python usdx-py package.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@interchained/usdx",
+  "version": "0.1.0",
+  "description": "Typed HTTP client SDK for the USDx wallet API — balance engine, NowPayments deposits, ITC PSBT withdrawals, OTC rate",
+  "keywords": [
+    "usdx",
+    "wallet",
+    "crypto",
+    "interchained",
+    "nowpayments",
+    "psbt",
+    "blockchain",
+    "balance",
+    "atomic",
+    "redis"
+  ],
+  "homepage": "https://github.com/interchained/usdx-js",
+  "bugs": {
+    "url": "https://github.com/interchained/usdx-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/interchained/usdx-js.git"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "Interchained <dev@interchained.org>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}