@zebec-network/exchange-card-sdk 1.11.4 → 1.12.0

package/README.md

@@ -1,56 +1,299 @@
-# Zebec Card SDK
+# Zebec Exchange Card SDK
 
-The Zebec Card SDK allows developers to integrate the functionality of purchasing and managing Zebec virtual cards into their applications. We currently support EVM chains (Ethereum, Binance Smart Chain (BSC), and Base) and Bittensor Network with the flexibility to toggle between mainnet and testnet environments based on configuration.
+The Zebec Exchange Card SDK lets developers fund Zebec virtual cards from a variety of non-EVM and alt‑EVM chains by transferring native assets or supported tokens to a Zebec-managed deposit vault. Each chain is exposed through a dedicated service that wraps vault discovery, balance checks, and transaction submission.
+
+Supported networks:
+
+- Aleo (native credits, USAD/USDCX stablecoins, public & private transfers)
+- Algorand (ALGO and ASA tokens, e.g. USDC)
+- Boba Network (Mainnet / Sepolia testnet — ETH and ERC‑20)
+- NEAR (NEAR and NEP‑141 fungible tokens)
+- Octa Space (OCTA native transfers)
+- Quai Network (QUAI native transfers)
+- Stellar (XLM and USDC)
+- XDB Chain (XDB native transfers)
+- XRPL / Ripple (XRP and issued tokens, with trust line setup)
+
+Every service can be toggled between mainnet (production) and testnet via the `sandbox` flag.
 
 ---
 
 ## Installation
 
-Install the Zebec Card SDK via npm:
-
 ```bash
-npm i @zebec-fintech/silver-card-sdk
+npm i @zebec-network/exchange-card-sdk
 ```
 
+Peer/runtime dependencies you may need depending on which service you use: `ethers`, `algosdk`, `xrpl`, `quais`, `@near-js/*`, `@provablehq/sdk`, `@stellar/stellar-sdk`.
+
+## Common Concepts
+
+### Sandbox mode
+
+Every service constructor accepts an options bag with a `sandbox` boolean. When `sandbox: true`, the service:
+
+- Talks to the Zebec sandbox API at `https://dev-super.api.zebec.io`.
+- Uses the testnet RPC for its chain (e.g. Sepolia for Boba, Testnet for Algorand/Stellar/XRPL, Futurenet for XDB, etc.).
+
+Defaults to `false` (production) when omitted.
+
+### Vault address
+
+Each service exposes `fetchVault(symbol?)` which calls Zebec's API to retrieve the destination deposit address (and optional memo `tag`) for a given asset symbol. All `transfer*` methods call `fetchVault` internally with the appropriate symbol — you generally do not need to call it yourself.
+
+### API health check
+
+The underlying `ZebecCardAPIService` exposes `ping()` which calls `/health` on the card API and returns `true` if reachable, otherwise throws.
+
+---
+
 ## Quick Start
 
-To get started, create an instance of `ZebecCardService` for EVM compatible networks or `ZebecCardTAOService` for Bittensor Network. This instance requires a signer, a chain ID (for EVM only), and configuration details, including API credentials.
+Pick the service that matches your source chain. Each service takes a wallet/signer and an optional `{ sandbox }` config.
+
+### Boba Network (EVM)
+
+```typescript
+import { ethers } from "ethers";
+import { BobaService } from "@zebec-network/exchange-card-sdk";
+
+const provider = new ethers.JsonRpcProvider("https://sepolia.boba.network");
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+
+const boba = new BobaService(signer, { sandbox: true });
+
+// Native ETH on Boba
+await boba.transferBobaEth({ amount: "0.01" });
+
+// ERC‑20 token on Boba
+await boba.transferToken({
+ amount: "10",
+ symbol: "BOBA-USDC",
+ tokenAddress: "0x...",
+});
+```
+
+### Octa Space (EVM)
+
+```typescript
+import { ethers } from "ethers";
+import { OctaService } from "@zebec-network/exchange-card-sdk";
+
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+const octa = new OctaService(signer, { sandbox: false });
+
+await octa.transferOcta({ amount: "1.5" });
+```
+
+### Quai Network
+
+```typescript
+import { QuaiService, QuaiWallet } from "@zebec-network/exchange-card-sdk";
+
+const wallet: QuaiWallet = {
+ address: "0x...",
+ signAndSendTransaction: async (tx) => {
+  /* sign & submit */
+  return "0xhash";
+ },
+};
+
+const quai = new QuaiService(wallet, { sandbox: false });
+const txHash = await quai.transferQuai({ amount: "2.0" });
+```
+
+### NEAR
+
+```typescript
+import { NearService, NearWallet } from "@zebec-network/exchange-card-sdk";
+
+const wallet: NearWallet = {
+ signerId: "alice.near",
+ signAndSendTransaction: async (transaction) => {
+  /* submit via near-api-js or wallet selector */
+ },
+};
+
+const near = new NearService(wallet, { sandbox: false });
+
+// Native NEAR
+await near.transferNear({ amount: "1.25" });
+
+// NEP‑141 token (e.g. USDC)
+await near.transferTokens({
+ amount: "10",
+ tokenContractId: "usdc.fakes.testnet",
+});
+```
+
+`registerAccountInTokenContract({ tokenContractId })` is also available; `transferTokens` already invokes the same `storage_deposit` flow internally when the destination is not yet registered.
+
+### XRPL (Ripple)
+
+```typescript
+import { XRPLService, XRPLWallet } from "@zebec-network/exchange-card-sdk";
+
+const wallet: XRPLWallet = {
+ address: "r...",
+ signTransaction: async (tx) => {
+  /* sign with xrpl.js Wallet or a wallet extension */
+ },
+};
+
+const xrpl = new XRPLService(wallet, { sandbox: true });
+
+// Native XRP
+await xrpl.transferXRP({ amount: "5" });
+
+// Issued token (requires a trust line)
+await xrpl.createTrustLine({
+ amount: "1000000",
+ token: { currency: "USD", issuer: "rIssuer..." },
+});
+await xrpl.transferTokens({
+ amount: "10",
+ token: { currency: "USD", issuer: "rIssuer..." },
+});
+```
+
+### Algorand
 
-> **Note**: Testnets (e.g., Sepolia, BSC Testnet) can only be used if `sandbox` mode is enabled.
+```typescript
+import algosdk from "algosdk";
+import { AlgorandService, AlgorandWallet } from "@zebec-network/exchange-card-sdk";
+
+const wallet: AlgorandWallet = {
+ address: "ALGO_ADDRESS",
+ signAndSendTransaction: async (txn) => {
+  /* sign and submit, return tx id */
+ },
+};
+
+const algo = new AlgorandService(wallet, { sandbox: true });
 
-Example:
+// Native ALGO
+await algo.transferAlgo({ amount: "1.0", note: "card top-up" });
 
-For EVM compatible networks:
+// ASA (e.g. USDC asset id 31566704 on mainnet, 10458941 on testnet)
+await algo.transferAsset({ assetId: 10458941, amount: "10" });
+```
 
-````typescript
-For Bittensor Network:
+### Stellar
 
 ```typescript
-import { ZebecCardTAOService } from '@zebec-fintech/silver-card-sdk';
+import { StellarService, StellarWallet } from "@zebec-network/exchange-card-sdk";
 
-const signer: <Keyring | Signer> = ... ; // Keyring or Signer instance from Wallet Extension
+const wallet: StellarWallet = {
+ address: "G...",
+ signTransaction: async (xdr) => {
+  /* sign and return signed xdr */
+ },
+};
 
-const service = new ZebecCardTAOService(
-    signer,
-    {
-        apiKey,
-        encryptionKey,
-    },
-    {
-        sandbox: true, // Set to true for development or testing
-    },
-);
-````
+const stellar = new StellarService(wallet, { sandbox: true });
 
-### Fetch Quote
+await stellar.transferXLM("5");
+await stellar.transferUSDC("10");
+```
 
-The `fetchQuote` method retrieves a quote for the specified amount in USD. The quote is used to calculate the corresponding token amount required for the card purchase. It expires in about 30 seconds.
+`transferXLM` attaches the vault's `tag` as a `Memo.id` automatically. The USDC issuer is preconfigured for both mainnet and testnet (see `STELLAR_USDC_ISSUER`).
 
-Note: The `fetchQuote` method should be called regularly. Make sure to check it's validity before proceeding with the purchase.
+### XDB Chain
 
-#### Code Example
+```typescript
+import { XDBService, XDBWalletInterface } from "@zebec-network/exchange-card-sdk";
+
+const wallet: XDBWalletInterface = {
+ address: "G...",
+ signTransaction: async (xdr) => {
+  /* sign and return signed xdr */
+ },
+};
+
+const xdb = new XDBService(wallet, { sandbox: false });
+await xdb.transferXDB("100");
+```
+
+### Aleo
 
 ```typescript
-const amount = "150.55"; // Amount in USD
-const quote = await service.fetchQuote(amount);
+import { AleoService, AleoWallet } from "@zebec-network/exchange-card-sdk";
+
+const wallet: AleoWallet = {
+ address: "aleo1...",
+ decrypt: async (ciphertext) => {
+  /* decrypt record ciphertext */
+ },
+ requestRecords: async (program, includePlaintext) => {
+  /* fetch records from wallet */
+ },
+ executeTransaction: async (opts) => {
+  /* execute program tx */
+ },
+};
+
+const aleo = new AleoService(wallet, undefined, { sandbox: false });
+
+// Native credits — public or private
+await aleo.transferCredit({ amount: "1.5", transferType: "public" });
+
+// Stablecoin (USAD / USDCX) — supports public and compliant private transfers
+await aleo.transferStableCoin({
+ programId: "usad_stablecoin.aleo",
+ amount: "10",
+ transferType: "private",
+});
+```
+
+For private stablecoin transfers, `AleoService` automatically:
+
+1. Fetches an unspent record with sufficient balance for the program.
+2. Builds a Sealance Merkle exclusion proof against the program's freeze list (`NETWORK_CONFIG[network].freezeListApi`) to prove the sender is not blocklisted.
+
+Balance helpers: `getPublicBalance()`, `getPrivateBalance()`, `getPublicTokenBalance(programId, symbol)`, `getPrivateTokenBalance(programId, symbol)`.
+
+---
+
+## Service Reference
+
+| Service           | Native transfer   | Token transfer                       | Notes                                        |
+| ----------------- | ----------------- | ------------------------------------ | -------------------------------------------- |
+| `BobaService`     | `transferBobaEth` | `transferToken`                      | Boba Mainnet (288) / Sepolia testnet (28882) |
+| `OctaService`     | `transferOcta`    | —                                    | Hard-coded chainId `800001`                  |
+| `QuaiService`     | `transferQuai`    | —                                    | Mainnet (9) / Testnet (15000)                |
+| `NearService`     | `transferNear`    | `transferTokens`                     | Auto `storage_deposit` for NEP‑141           |
+| `XRPLService`     | `transferXRP`     | `transferTokens` + `createTrustLine` | Memo / destination tag handled automatically |
+| `AlgorandService` | `transferAlgo`    | `transferAsset`                      | Validates ASA opt-in on recipient            |
+| `StellarService`  | `transferXLM`     | `transferUSDC`                       | Submission retries with exponential backoff  |
+| `XDBService`      | `transferXDB`     | —                                    | LiveNet / Futurenet network passphrases      |
+| `AleoService`     | `transferCredit`  | `transferStableCoin`                 | Public + private with compliance proof       |
+
+### Utilities
+
+The SDK re-exports helpers from `utils`:
+
+- `parseAlgo` / `formatAlgo` — ALGO ↔ microAlgo conversion
+- `parseAlgorandAsset` / `formatAlgorandAsset` — ASA base-unit conversion
+- `getAssetDecimals(client, assetId)` — cached ASA decimals lookup
+- `toMicroUnits` / `fromMicroUnits` — generic decimal conversion (used by Aleo)
+- `getTokenBySymbol(symbol, network)` — fetch Aleo token metadata from `api.provable.com`
+
+And from `constants`:
+
+- `CARD_API_URL` — Production / Sandbox base URLs
+- `NEAR_RPC_URL`, `XRPL_RPC_URL`, `STELLAR_RPC_URL`, `XDB_RPC_URL`, `ALGORAND_RPC_URL`
+- `STELLAR_USDC_ISSUER`, `BITCOIN_ENDPOINTS`, `ALEO_NETWORK_CLIENT_URL`
+- `BOBA_CHAIN_ID`, `QUAI_CHAIN_ID`, `XDB_NETWORK`
+- Default EVM/Quai gas constants, `PLATFORM_FEE`
+
+### Raw API client
+
+If you need direct access to the Zebec card API:
+
+```typescript
+import { ZebecCardAPIService } from "@zebec-network/exchange-card-sdk";
+
+const api = new ZebecCardAPIService(true); // sandbox
+await api.ping();
+const vault = await api.fetchVault("XRP");
 ```

package/dist/helpers/apiHelpers.d.ts

@@ -3,8 +3,23 @@ export declare class ZebecCardAPIService {
     private readonly api;
     constructor(sandbox?: boolean);
     ping(): Promise<boolean>;
+    /**
+     * @deprecated Use {@link fetchVaultByTokenAddress} instead
+     *
+     * @param symbol Token symbol
+     * @returns An object containing address and tag (optional)
+     */
     fetchVault(symbol: string): Promise<{
         address: string;
         tag?: string;
     }>;
+    /**
+     *
+     * @param address mint address
+     * @returns An object containing address and tag (optional)
+     */
+    fetchVaultByTokenAddress(address: string): Promise<{
+        address: string;
+        tag?: string;
+    }>;
 }

package/dist/helpers/apiHelpers.js

@@ -13,12 +13,46 @@ export class ZebecCardAPIService {
             await this.api.get("/health");
             return true;
         }
-        catch (error) {
+        catch (_) {
             throw new Error("Card service is down. Please try again later.");
         }
     }
+    /**
+     * @deprecated Use {@link fetchVaultByTokenAddress} instead
+     *
+     * @param symbol Token symbol
+     * @returns An object containing address and tag (optional)
+     */
     async fetchVault(symbol) {
-        const { data } = await this.api.get(`/tokens/deposit-address`, { params: { symbol } });
+        const { data } = await this.api.get(`/tokens/deposit-address`, {
+            params: { symbol },
+        });
+        return data.data;
+    }
+    /**
+     *
+     * @param address mint address
+     * @returns An object containing address and tag (optional)
+     */
+    async fetchVaultByTokenAddress(address) {
+        const response = await this.api.get(`/tokens/deposit-address`, {
+            params: {
+                mintAddress: address,
+            },
+        });
+        const data = response.data;
+        if (!data ||
+            typeof data !== "object" ||
+            !("data" in data) ||
+            !data.data ||
+            typeof data.data !== "object" ||
+            !("address" in data.data) ||
+            typeof data.data.address !== "string") {
+            throw new Error(`Invalid response shape for fetching vault address by mint address. data:\n${String(data)}`);
+        }
+        if ("tag" in data.data && data.data.tag && typeof data.data.tag !== "string") {
+            throw new Error(`Invalid response shape for fetching vault address by mint address. data:\n${String(data)}`);
+        }
         return data.data;
     }
 }

package/dist/services/aleoService.d.ts

@@ -105,7 +105,7 @@ export declare class AleoService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByTokenAddress(address: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/aleoService.js

@@ -54,8 +54,8 @@ export class AleoService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    async fetchVault(symbol = "ALEO") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByTokenAddress(address) {
+        const data = await this.apiService.fetchVaultByTokenAddress(address);
         return data;
     }
     /**
@@ -126,7 +126,7 @@ export class AleoService {
             recipient = params.recipient;
         }
         else {
-            const vault = await this.fetchVault("ALEO");
+            const vault = await this.fetchVaultByTokenAddress("credits.aleo");
             if (!vault) {
                 throw new Error("Failed to fetch vault address");
             }
@@ -163,14 +163,14 @@ export class AleoService {
         const privateFee = params?.privateFee || false;
         const fee = toMicroUnits(params.fee || 0.1, 6);
         const programId = this.sandbox ? `test_${params.programId}` : params.programId;
-        const tokenSymbol = params.programId === "usad_stablecoin.aleo" ? "USAD" : "USDCX";
+        const tokenSymbol = params.programId === "usad_stablecoin.aleo" ? "usad" : "usdcx";
         const functionName = transferType === "public" ? "transfer_public" : "transfer_private";
         let recipient;
         if (params.recipient) {
             recipient = params.recipient;
         }
         else {
-            const vault = await this.fetchVault(tokenSymbol);
+            const vault = await this.fetchVaultByTokenAddress(params.programId);
             if (!vault) {
                 throw new Error("Failed to fetch vault address");
             }
@@ -186,7 +186,7 @@ export class AleoService {
                 // For private transfer, we need to find a record with sufficient balance
                 const [record, complianceProof] = await Promise.all([
                     this._getRecord(programId),
-                    this._getComplianceProof(tokenSymbol.toLowerCase(), this.wallet.address, this.sandbox ? Network.TESTNET : Network.MAINNET),
+                    this._getComplianceProof(tokenSymbol, this.wallet.address, this.sandbox ? Network.TESTNET : Network.MAINNET),
                 ]);
                 inputs = [recipient, amountInMicroUnits, record, complianceProof];
                 break;

package/dist/services/algorandService.d.ts

@@ -31,7 +31,7 @@ export declare class AlgorandService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByAssetId(assetId: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/algorandService.js

@@ -17,8 +17,8 @@ export class AlgorandService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    async fetchVault(symbol = "ALGO") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByAssetId(assetId) {
+        const data = await this.apiService.fetchVaultByTokenAddress(assetId);
         return data;
     }
     /**
@@ -35,7 +35,7 @@ export class AlgorandService {
             if (senderBalance < parsedAmount + minBalance) {
                 throw new Error(`Insufficient balance. Need ${formatAlgo(parsedAmount + minBalance)} ALGO, have ${formatAlgo(senderBalance)} ALGO`);
             }
-            const vault = await this.fetchVault("ALGO");
+            const vault = await this.fetchVaultByAssetId("algo");
             const recipientAddress = vault.address;
             // Validate recipient address
             if (!algosdk.isValidAddress(recipientAddress)) {
@@ -81,7 +81,7 @@ export class AlgorandService {
             if (senderAlgoBalance < minAlgoForFees) {
                 throw new Error(`Insufficient ALGO for transaction fees. Need at least ${formatAlgo(minAlgoForFees)} ALGO for fees`);
             }
-            const vault = await this.fetchVault("ALGO-USDC");
+            const vault = await this.fetchVaultByAssetId(config.assetId.toString());
             const recipientAddress = vault.address;
             // Validate recipient address
             if (!algosdk.isValidAddress(recipientAddress)) {

package/dist/services/bobaService.d.ts

@@ -7,7 +7,6 @@ export type TransferBobaParams = {
 export type TransferTokenParams = {
     amount: string | number;
     tokenAddress: string;
-    symbol: string;
     overrides?: Omit<ethers.Overrides, "from" | "value" | "chainId">;
 };
 export declare class BobaService {
@@ -23,7 +22,7 @@ export declare class BobaService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    fetchVault(symbol: string): Promise<{
+    fetchVaultByTokenAddress(address: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/bobaService.js

@@ -18,14 +18,14 @@ export class BobaService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    async fetchVault(symbol) {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByTokenAddress(address) {
+        const data = await this.apiService.fetchVaultByTokenAddress(address);
         return data;
     }
     async transferBobaEth(params) {
         const parsedAmount = ethers.parseEther(params.amount.toString());
         const provider = this.signer.provider;
-        const vault = await this.fetchVault("BOBA-ETH");
+        const vault = await this.fetchVaultByTokenAddress("boba-eth");
         const recipientAddress = vault.address;
         if (!provider) {
             throw new Error("There is no provider in signer instance.");
@@ -53,7 +53,7 @@ export class BobaService {
         const tokenContract = ERC20__factory.connect(params.tokenAddress, this.signer);
         const tokenDecimals = await tokenContract.decimals();
         const parsedAmount = ethers.parseUnits(params.amount.toString(), tokenDecimals);
-        const vault = await this.fetchVault(params.symbol);
+        const vault = await this.fetchVaultByTokenAddress(params.tokenAddress);
         const recipientAddress = vault.address;
         const senderBalance = await tokenContract.balanceOf(this.signer);
         if (senderBalance < parsedAmount) {

package/dist/services/nearService.d.ts

@@ -1,5 +1,5 @@
-import { Provider } from "@near-js/providers";
-import { FinalExecutionOutcome } from "@near-js/types";
+import { type Provider } from "@near-js/providers";
+import type { FinalExecutionOutcome } from "@near-js/types";
 export interface CreateAccountAction {
     type: "CreateAccount";
 }
@@ -89,7 +89,7 @@ export declare class NearService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByTokenAddress(address: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/nearService.js

@@ -1,7 +1,7 @@
-import assert from "assert";
-import { BigNumber } from "bignumber.js";
 import { JsonRpcProvider } from "@near-js/providers";
 import { parseNearAmount } from "@near-js/utils";
+import assert from "assert";
+import { BigNumber } from "bignumber.js";
 import { NEAR_RPC_URL } from "../constants";
 import { ZebecCardAPIService } from "../helpers/apiHelpers";
 /**
@@ -38,13 +38,13 @@ export class NearService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    async fetchVault(symbol = "NEAR") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByTokenAddress(address) {
+        const data = await this.apiService.fetchVaultByTokenAddress(address);
         return data;
     }
     async transferNear(params) {
         const signerId = params.signerId ? params.signerId : this.wallet.signerId;
-        const fetchVault = await this.fetchVault();
+        const fetchVault = await this.fetchVaultByTokenAddress("near");
         const destination = fetchVault.address;
         console.debug("destination:", destination);
         const parsedAmount = parseNearAmount(params.amount);
@@ -101,10 +101,10 @@ export class NearService {
     async transferTokens(params) {
         const signerId = params.signerId ? params.signerId : this.wallet.signerId;
         console.log("signerId:", signerId);
-        const fetchVault = await this.fetchVault("NEAR-USDC");
+        const fetchVault = await this.fetchVaultByTokenAddress(params.tokenContractId);
         const destination = fetchVault.address;
         console.debug("destination:", destination);
-        let actions = [];
+        const actions = [];
         const GAS = "30000000000000";
         const storageBalanceBoundsResult = await this.provider.query({
             request_type: "call_function",

package/dist/services/octaService.d.ts

@@ -1,4 +1,4 @@
-import { ethers } from "ethers";
+import { type ethers } from "ethers";
 export type TransferOctaParams = {
     amount: string | number;
     overrides?: Omit<ethers.Overrides, "from" | "value" | "chainId">;
@@ -14,7 +14,7 @@ export declare class OctaService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByTokenAddress(address: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/octaService.js

@@ -13,14 +13,14 @@ export class OctaService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    async fetchVault(symbol = "OCTA") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByTokenAddress(address) {
+        const data = await this.apiService.fetchVaultByTokenAddress(address);
         return data;
     }
     async transferOcta(params) {
         const parsedAmount = parseEther(params.amount.toString());
         const provider = this.signer.provider;
-        const vault = await this.fetchVault();
+        const vault = await this.fetchVaultByTokenAddress("octa-native");
         const recipientAddress = vault.address;
         if (!provider) {
             throw new Error("There is no provider in signer instance.");

package/dist/services/quaiService.d.ts

@@ -1,4 +1,4 @@
-import { QuaiTransactionRequest } from "quais/providers";
+import type { QuaiTransactionRequest } from "quais/providers";
 export type TransferQuaiParams = {
     amount: string | number;
     overrides?: Omit<QuaiTransactionRequest, "from" | "value" | "chainId">;
@@ -18,7 +18,7 @@ export declare class QuaiService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    fetchVault(symbol: string): Promise<{
+    fetchVaultByTokenAddress(address: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/quaiService.js

@@ -13,13 +13,13 @@ export class QuaiService {
      *
      * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
      */
-    async fetchVault(symbol) {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByTokenAddress(address) {
+        const data = await this.apiService.fetchVaultByTokenAddress(address);
         return data;
     }
     async transferQuai(params) {
         const parsedAmount = parseQuai(params.amount.toString());
-        const vault = await this.fetchVault("QUAI");
+        const vault = await this.fetchVaultByTokenAddress("quai");
         const recipientAddress = vault.address;
         const request = {
             ...params.overrides,

package/dist/services/stellarService.d.ts

@@ -1,4 +1,4 @@
-import { Asset, Horizon } from "@zebec-fintech/stellar-sdk";
+import { Asset, Horizon } from "@stellar/stellar-sdk";
 export interface StellarWallet {
     address: string;
     signTransaction: (txXdr: string) => Promise<string>;
@@ -22,42 +22,42 @@ export declare class StellarService {
     /**
      * Fetches the Vault address.
      *
-     * @returns {Promise<string>} A promise that resolves to the Vault address.
+     * @returns A promise that resolves to the Vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByAsset(asset: string): Promise<{
         address: string;
         tag?: string;
     }>;
     /**
      * Purchases a card by transferring XDB tokens.
      *
-     * @param params - The parameters required to purchase a card.
+     * @param amount - The amount required to purchase a card.
      * @returns A promise that resolves to an array containing the transaction details and the API response.
-     * @throws {InvalidEmailError} If the recipient's email address is invalid.
-     * @throws {Error} If the quote is invalid or expired, if there is not enough balance, or if the transaction fails.
+     * @throws If the recipient's email address is invalid.
+     * @throws If the quote is invalid or expired, if there is not enough balance, or if the transaction fails.
      */
     transferXLM(amount: string): Promise<string>;
     /**
      * Transfers USDC tokens.
      *
-     * @param {string} amount - The amount of USDC to transfer.
-     * @returns {Promise<string>} A promise that resolves to the transaction hash.
-     * @throws {Error} If there is not enough USDC balance or if the transaction fails.
+     * @param amount - The amount of USDC to transfer.
+     * @returns A promise that resolves to the transaction hash.
+     * @throws If there is not enough USDC balance or if the transaction fails.
      */
     transferUSDC(amount: string): Promise<string>;
     /**
      * Retrieves the balance of the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the balance for.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the wallet.
+     * @param wallet - The public key of the wallet to get the balance for.
+     * @returns - A promise that resolves to the balance of the wallet.
      */
     getWalletBalance(wallet: string): Promise<string>;
     /**
      * Retrieves the balance of a specific token for the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the token balance for.
-     * @param {Asset} asset - The asset object representing the token.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the token.
+     * @param wallet - The public key of the wallet to get the token balance for.
+     * @param asset - The asset object representing the token.
+     * @returns A promise that resolves to the balance of the token.
      */
     getTokenBalance(wallet: string, asset: Asset): Promise<string>;
     getAsset(assetCode: string, assetIssuer: string): Promise<Asset>;

package/dist/services/stellarService.js

@@ -1,4 +1,4 @@
-import { Asset, Horizon, Memo, Networks, Operation, TimeoutInfinite, TransactionBuilder, } from "@zebec-fintech/stellar-sdk";
+import { Asset, Horizon, Memo, Networks, Operation, TimeoutInfinite, TransactionBuilder, } from "@stellar/stellar-sdk";
 import { STELLAR_RPC_URL, STELLAR_USDC_ISSUER } from "../constants";
 import { ZebecCardAPIService } from "../helpers/apiHelpers";
 export class StellarService {
@@ -23,27 +23,27 @@ export class StellarService {
     /**
      * Fetches the Vault address.
      *
-     * @returns {Promise<string>} A promise that resolves to the Vault address.
+     * @returns A promise that resolves to the Vault address.
      */
-    async fetchVault(symbol = "XLM") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByAsset(asset) {
+        const data = await this.apiService.fetchVaultByTokenAddress(asset);
         return data;
     }
     /**
      * Purchases a card by transferring XDB tokens.
      *
-     * @param params - The parameters required to purchase a card.
+     * @param amount - The amount required to purchase a card.
      * @returns A promise that resolves to an array containing the transaction details and the API response.
-     * @throws {InvalidEmailError} If the recipient's email address is invalid.
-     * @throws {Error} If the quote is invalid or expired, if there is not enough balance, or if the transaction fails.
+     * @throws If the recipient's email address is invalid.
+     * @throws If the quote is invalid or expired, if there is not enough balance, or if the transaction fails.
      */
     async transferXLM(amount) {
         // Fetch deposit address
-        const vault = await this.fetchVault();
+        const vault = await this.fetchVaultByAsset("CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA");
         // Prepare transaction
         const account = await this.server.loadAccount(this.wallet.address);
         const fee = await this.server.fetchBaseFee();
-        const memo = Memo.id(vault.tag?.toString() || "");
+        const memo = Memo.id(vault.tag?.toString() || "0");
         // Check Wallet balance
         const balance = await this.getWalletBalance(this.wallet.address);
         if (Number(balance) < Number(amount)) {
@@ -92,18 +92,18 @@ export class StellarService {
     /**
      * Transfers USDC tokens.
      *
-     * @param {string} amount - The amount of USDC to transfer.
-     * @returns {Promise<string>} A promise that resolves to the transaction hash.
-     * @throws {Error} If there is not enough USDC balance or if the transaction fails.
+     * @param amount - The amount of USDC to transfer.
+     * @returns A promise that resolves to the transaction hash.
+     * @throws If there is not enough USDC balance or if the transaction fails.
      */
     async transferUSDC(amount) {
+        // Create USDC asset object
+        const usdcAsset = new Asset("USDC", this.sandbox ? STELLAR_USDC_ISSUER.Sandbox : STELLAR_USDC_ISSUER.Production);
         // Fetch deposit address
-        const vault = await this.fetchVault("XLM-USDC");
+        const vault = await this.fetchVaultByAsset(`${usdcAsset.code}:${usdcAsset.issuer}`);
         // Prepare transaction
         const account = await this.server.loadAccount(this.wallet.address);
         const fee = await this.server.fetchBaseFee();
-        // Create USDC asset object
-        const usdcAsset = new Asset("USDC", this.sandbox ? STELLAR_USDC_ISSUER.Sandbox : STELLAR_USDC_ISSUER.Production);
         // Check Wallet balance
         const balance = await this.getTokenBalance(this.wallet.address, usdcAsset);
         if (Number(balance) < Number(amount)) {
@@ -151,8 +151,8 @@ export class StellarService {
     /**
      * Retrieves the balance of the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the balance for.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the wallet.
+     * @param wallet - The public key of the wallet to get the balance for.
+     * @returns - A promise that resolves to the balance of the wallet.
      */
     async getWalletBalance(wallet) {
         const account = await this.server.loadAccount(wallet);
@@ -162,9 +162,9 @@ export class StellarService {
     /**
      * Retrieves the balance of a specific token for the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the token balance for.
-     * @param {Asset} asset - The asset object representing the token.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the token.
+     * @param wallet - The public key of the wallet to get the token balance for.
+     * @param asset - The asset object representing the token.
+     * @returns A promise that resolves to the balance of the token.
      */
     async getTokenBalance(wallet, asset) {
         const account = await this.server.loadAccount(wallet);

package/dist/services/xdbService.d.ts

@@ -1,4 +1,4 @@
-import { Asset, Horizon } from "@zebec-fintech/stellar-sdk";
+import { Asset, Horizon } from "@stellar/stellar-sdk";
 import { ZebecCardAPIService } from "../helpers/apiHelpers";
 export interface XDBWalletInterface {
     address: string;
@@ -25,7 +25,7 @@ export declare class XDBService {
      *
      * @returns {Promise<string>} A promise that resolves to the Vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByAsset(asset: string): Promise<{
         address: string;
         tag?: string;
     }>;
@@ -34,23 +34,22 @@ export declare class XDBService {
      *
      * @param params - The parameters required to purchase a card.
      * @returns A promise that resolves to an array containing the transaction details and the API response.
-     * @throws {InvalidEmailError} If the recipient's email address is invalid.
-     * @throws {Error} If the quote is invalid or expired, if there is not enough balance, or if the transaction fails.
+     * @throws `Error` If there is not enough balance, or if the transaction fails.
      */
     transferXDB(amount: string): Promise<string>;
     /**
      * Retrieves the balance of the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the balance for.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the wallet.
+     * @param wallet - The public key of the wallet to get the balance for.
+     * @returns - A promise that resolves to the balance of the wallet.
      */
     getNativeBalance(wallet: string): Promise<string>;
     /**
      * Retrieves the balance of a specific token for the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the token balance for.
-     * @param {Asset} asset - The asset object representing the token.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the token.
+     * @param wallet - The public key of the wallet to get the token balance for.
+     * @param asset - The asset object representing the token.
+     * @returns - A promise that resolves to the balance of the token.
      */
     getTokenBalance(wallet: string, asset: Asset): Promise<string>;
     getAsset(assetCode: string, assetIssuer: string): Asset;

package/dist/services/xdbService.js

@@ -1,4 +1,4 @@
-import { Asset, Horizon, Memo, Operation, TimeoutInfinite, TransactionBuilder, } from "@zebec-fintech/stellar-sdk";
+import { Asset, Horizon, Memo, Operation, TimeoutInfinite, TransactionBuilder, } from "@stellar/stellar-sdk";
 import { XDB_NETWORK, XDB_RPC_URL } from "../constants";
 import { ZebecCardAPIService } from "../helpers/apiHelpers";
 export class XDBService {
@@ -25,8 +25,8 @@ export class XDBService {
      *
      * @returns {Promise<string>} A promise that resolves to the Vault address.
      */
-    async fetchVault(symbol = "XDB") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByAsset(asset) {
+        const data = await this.apiService.fetchVaultByTokenAddress(asset);
         return data;
     }
     /**
@@ -34,12 +34,11 @@ export class XDBService {
      *
      * @param params - The parameters required to purchase a card.
      * @returns A promise that resolves to an array containing the transaction details and the API response.
-     * @throws {InvalidEmailError} If the recipient's email address is invalid.
-     * @throws {Error} If the quote is invalid or expired, if there is not enough balance, or if the transaction fails.
+     * @throws `Error` If there is not enough balance, or if the transaction fails.
      */
     async transferXDB(amount) {
         // Fetch deposit address
-        const vault = await this.fetchVault("XDB");
+        const vault = await this.fetchVaultByAsset("xdb");
         const recipientAddress = vault.address;
         const tag = vault.tag || "0";
         // Prepare transaction
@@ -94,8 +93,8 @@ export class XDBService {
     /**
      * Retrieves the balance of the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the balance for.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the wallet.
+     * @param wallet - The public key of the wallet to get the balance for.
+     * @returns - A promise that resolves to the balance of the wallet.
      */
     async getNativeBalance(wallet) {
         const account = await this.server.loadAccount(wallet);
@@ -105,9 +104,9 @@ export class XDBService {
     /**
      * Retrieves the balance of a specific token for the specified wallet.
      *
-     * @param {string} wallet - The public key of the wallet to get the token balance for.
-     * @param {Asset} asset - The asset object representing the token.
-     * @returns {Promise<string>} - A promise that resolves to the balance of the token.
+     * @param wallet - The public key of the wallet to get the token balance for.
+     * @param asset - The asset object representing the token.
+     * @returns - A promise that resolves to the balance of the token.
      */
     async getTokenBalance(wallet, asset) {
         const account = await this.server.loadAccount(wallet);

package/dist/services/xrplService.d.ts

@@ -1,4 +1,4 @@
-import { BaseTransaction, Client, SubmittableTransaction, Transaction, TxResponse } from "xrpl";
+import { type BaseTransaction, Client, type SubmittableTransaction, type Transaction, type TxResponse } from "xrpl";
 export interface XRPLWallet {
     address: string;
     signTransaction: (transaction: SubmittableTransaction | BaseTransaction) => Promise<string>;
@@ -11,11 +11,11 @@ export declare class XRPLService {
         sandbox?: boolean;
     });
     /**
-     * Fetches the Bitcoin vault address.
+     * Fetches the xrpl vault address.
      *
-     * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
+     * @returns A promise that resolves to the vault address.
      */
-    fetchVault(symbol?: string): Promise<{
+    fetchVaultByTokenAddress(address: string): Promise<{
         address: string;
         tag?: string;
     }>;

package/dist/services/xrplService.js

@@ -13,12 +13,12 @@ export class XRPLService {
         this.client = new Client(xrplNetwork);
     }
     /**
-     * Fetches the Bitcoin vault address.
+     * Fetches the xrpl vault address.
      *
-     * @returns {Promise<{ address: string }>} A promise that resolves to the vault address.
+     * @returns A promise that resolves to the vault address.
      */
-    async fetchVault(symbol = "XRP") {
-        const data = await this.apiService.fetchVault(symbol);
+    async fetchVaultByTokenAddress(address) {
+        const data = await this.apiService.fetchVaultByTokenAddress(address);
         return data;
     }
     async transferXRP(params) {
@@ -27,13 +27,13 @@ export class XRPLService {
         if (!isValidAddress(walletAddress)) {
             throw new Error("Invalid wallet address");
         }
-        const { address: destination, tag } = await this.fetchVault();
+        const { address: destination, tag } = await this.fetchVaultByTokenAddress("xrp");
         console.debug("destination:", destination);
         console.debug("tag:", tag);
         if (!isValidAddress(destination)) {
             throw new Error("Invalid destination address");
         }
-        const destinationTag = tag && tag !== "" ? parseInt(tag) : undefined;
+        const destinationTag = tag && tag !== "" ? parseInt(tag, 10) : undefined;
         const amountInDrops = xrpToDrops(params.amount);
         const transaction = {
             TransactionType: "Payment",
@@ -49,9 +49,6 @@ export class XRPLService {
             const response = await this.client.submitAndWait(signedTx);
             return response;
         }
-        catch (error) {
-            throw error;
-        }
         finally {
             await this.client.disconnect();
         }
@@ -62,13 +59,13 @@ export class XRPLService {
         if (!isValidAddress(walletAddress)) {
             throw new Error("Invalid wallet address");
         }
-        const { address: destination, tag } = await this.fetchVault();
+        const { address: destination, tag } = await this.fetchVaultByTokenAddress(params.token.currency);
         console.debug("destination:", destination);
         console.debug("tag:", tag);
         if (!isValidAddress(destination)) {
             throw new Error("Invalid destination address");
         }
-        const destinationTag = tag && tag !== "" ? parseInt(tag) : undefined;
+        const destinationTag = tag && tag !== "" ? parseInt(tag, 10) : undefined;
         const transaction = {
             TransactionType: "Payment",
             Account: walletAddress,
@@ -87,9 +84,6 @@ export class XRPLService {
             const response = await this.client.submitAndWait(signedTx);
             return response;
         }
-        catch (error) {
-            throw error;
-        }
         finally {
             await this.client.disconnect();
         }
@@ -115,9 +109,6 @@ export class XRPLService {
             const response = await this.client.submitAndWait(signedTx);
             return response;
         }
-        catch (error) {
-            throw error;
-        }
         finally {
             await this.client.disconnect();
         }
@@ -134,9 +125,6 @@ export class XRPLService {
             });
             return balances;
         }
-        catch (error) {
-            throw error;
-        }
         finally {
             await this.client.disconnect();
         }

package/package.json

@@ -6,27 +6,27 @@
 		"@near-js/transactions": "^2.5.1",
 		"@near-js/types": "^2.5.1",
 		"@near-js/utils": "^2.5.1",
-		"@provablehq/sdk": "^0.10.2",
-		"@zebec-fintech/stellar-sdk": "^15.0.2",
-		"algosdk": "^3.4.0",
-		"axios": "^1.15.0",
-		"bignumber.js": "^10.0.2",
-		"ethers": "^6.15.0",
-		"quais": "^1.0.0-alpha.52",
-		"xrpl": "^4.4.1"
+		"@provablehq/sdk": "^0.11.0",
+		"@stellar/stellar-sdk": "^15.1.0",
+		"algosdk": "^3.5.2",
+		"axios": "^1.16.0",
+		"bignumber.js": "^11.1.1",
+		"ethers": "^6.16.0",
+		"quais": "^1.0.0-alpha.54",
+		"xrpl": "^4.6.0"
 	},
 	"description": "An sdk for purchasing silver card in zebec",
 	"devDependencies": {
-		"@algorandfoundation/algokit-utils": "^9.1.2",
+		"@algorandfoundation/algokit-utils": "^9.2.0",
 		"@near-js/accounts": "^2.5.1",
 		"@near-js/keystores": "^2.5.1",
 		"@near-js/signers": "^2.5.1",
 		"@near-js/tokens": "^2.5.1",
 		"@typechain/ethers-v6": "^0.5.1",
 		"@types/mocha": "^10.0.10",
-		"@types/node": "^25.6.0",
-		"dotenv": "^17.2.2",
-		"mocha": "^11.7.2",
+		"@types/node": "^25.7.0",
+		"dotenv": "^17.4.2",
+		"mocha": "^11.7.5",
 		"prettier": "^3.6.2",
 		"rimraf": "^6.0.1",
 		"ts-mocha": "^11.1.0",
@@ -63,5 +63,5 @@
 	},
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.11.4"
+	"version": "1.12.0"
 }