Skip to main content

​
Installation

npm install js-1151
# or
pnpm add js-1151
# or
yarn add js-1151
Install the package with your preferred Node.js package manager. All commands install the same versioned package published to npm.

​
Creating a client

import Client from 'js-1151';

const client = new Client(process.env.API_KEY!, undefined, {
  timeout: 20_000, // optional override (default 30s)
});
  • Pass your API key via the apiKey property.
  • Provide fetchFn when running in environments without a global fetch implementation.

​
Creating and retrieving wallets

const wallet = await client.createWallet({
  name: 'first_wallet',
  network: 'eth',
  testnet: true,
  metadata: {
    customerId: 'cust_123',
    environment: 'staging',
  },
});
console.log(wallet.id, wallet.address, wallet.metadata?.customerId);

const fetched = await client.getWallet({ walletId: wallet.id });
console.log(fetched.lastUsed, fetched.metadata);
createWallet resolves to a Wallet instance with helper getters, including metadata when you pass a JSON object. getWallet accepts the wallet ID (w_<uuid>), the on-chain address, or the wallet name and returns an empty wallet shell if the resource does not exist.

​
Deleting wallets

await client.deleteWallet({ walletId: wallet.id });

// or delete by address when you do not have the ID at hand
await client.deleteWallet({ walletId: wallet.address });
  • deleteWallet resolves when the API confirms the removal; it throws if the wallet is missing or unauthorized.
  • Pass either the wallet ID (w_<uuid>) or the on-chain address to delete the resource.

​
Sending assets

const [success, txHash] = await wallet.send({
  asset: 'ETH',
  amount: 0.05,
  destination: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  metadata: { invoice: 'INV-42', customerId: 'cust_123' },
});

if (!success) {
  console.error('Transfer failed:', txHash);
}
  • asset must align with the wallet network (ETH, USDC, USDT, BTC, TRX) and is optional for ETH when using ethErc20Contract.
  • Failed broadcasts return [false, "<provider message>"] so you can surface the reason in logs or UI.
  • Include metadata to persist arbitrary JSON with the transaction.
  • client.sendFromWallet({ walletId, ... }) accepts a wallet ID or address; wallet.send({ ... }) reads the ID from the instance automatically.
The tuple returned by wallet.send mirrors the REST API: a boolean indicating success and either the transaction hash or a provider error. Retry logic should branch on the boolean rather than the HTTP status alone.

​
Customizing fees

await client.sendFromWallet({
  walletId: wallet.id,
  asset: 'ETH',
  amount: 0.05,
  destination: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  btcFee: 'high',
  ethFee: 120_000,
  ethMaxPriorityFeePerGas: 2_000_000_000,
  ethMaxFeePerGas: 3_500_000_000,
  metadata: { invoice: 'INV-42' },
});
  • btcFee accepts a tier ("low", "normal", "high") or a sat/kByte string when broadcasting BTC transactions.
  • ethFee lets you override the gas limit (defaults to 21,000 for ETH and 65,000 for ERC-20 transfers).
  • ethMaxPriorityFeePerGas and ethMaxFeePerGas mirror the EIP-1559 fields in wei; keep the max fee greater than or equal to the priority fee.
  • Include metadata in the options object to store additional identifiers alongside the resulting transaction.
  • All properties are optional—omit them to use the API-estimated values.
You can pass the same options to wallet.send(...); the helper forwards them to client.sendFromWallet so per-transaction fee control works in either form.

​
Custom ERC-20 by contract

Send any ERC-20 by specifying its contract. Omit asset and provide ethErc20Contract as a string: 
const [ok, hashOrError] = await client.sendFromWallet({
  walletId: wallet.id,
  amount: 12.5,
  destination: '0xA1b02d8c67b0FDCF4E379855868DeB470E169cfB',
  ethErc20Contract: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  ethFee: 65_000,
});
Notes:
  • For Ethereum, provide either asset or ethErc20Contract (not both).
  • amount is in token units for ERC-20 transfers.

​
BTC multi-output sends

For Bitcoin, you can send to multiple outputs in a single transaction by passing a destinations mapping of { address: amount } and omitting amount/destination: 
// From a Client instance
await client.sendFromWallet({
  walletId: wallet.id,
  asset: 'BTC',
  destinations: {
    'bc1qaddr1...': 0.004,
    'bc1qaddr2...': 0.006,
  },
  btcFee: 'normal',
  metadata: { batch: true },
});

// From a Wallet instance
await wallet.send({
  asset: 'BTC',
  destinations: {
    'bc1qaddr1...': 0.004,
    'bc1qaddr2...': 0.006,
  },
  btcFee: 'low',
});
Notes:
  • Provide exactly one shape: either { amount, destination } or { destinations }.
  • Multi-output is currently supported only for BTC.

​
Accessing UTXOs

const utxos = await client.getUtxos({ walletId: 'w_btc_wallet' });
for (const utxo of utxos) {
  console.log(`${utxo.txid}:${utxo.vout} = ${utxo.amountBtc} BTC`);
}
Each UTXO helper exposes txid, vout, amountBtc, confirmations, and the original payload via rawData.

​
Retrieving transactions

const txById = await client.getTransaction({ txId: 'tx_2c4f2b01-5f49-4c66-b379-a9e0c7df8f5e' });
console.log(txById.asset, txById.amount, txById.success);

const txByHash = await client.getTransaction({ txId: '0x3f9d0b55c8122df4d6d2b41cb6c90a3f7bf8f4f8d4f3c7d1a5b2c3d4e5f6a7b8' });
console.log(txByHash.associatedWallet);
  • getTransaction accepts either the 1151 transaction ID (tx_<uuid>) or the on-chain transaction hash and returns a Transaction helper.
  • Transaction instances expose getters for id, direction, asset, amount, destination, success, metadata, and rawData for the full payload.
const transactions = await client.getWalletTransactions({ walletId: wallet.id });
// or, using the wallet helper
const sameResult = await wallet.transactions();

for (const transaction of transactions) {
  console.log(transaction.id, transaction.createdAt, transaction.metadata);
}
The wallet listing returns an array of Transaction helpers in reverse chronological order so you can display recent activity immediately.

​
Error handling

try {
  await client.deleteWallet({ walletId: 'non-existent' });
} catch (error) {
  if (error instanceof HttpError) {
    console.error('HTTP status', error.response.status);
  } else {
    throw error;
  }
}
  • Non-2xx responses throw HttpError with the original Response for inspection.
  • Requests automatically abort after the configured timeout and throw a standard Error.
  • The SDK adds your API key to the JSON payload automatically; do not duplicate it in the body.
Wrap calls in try/catch blocks so you can surface actionable error messages to your operators or user interfaces.

​
Type support

The package ships with full TypeScript definitions for Client, Wallet, UTXO, and the return payloads. You can import the types from js-1151: 
import type { WalletFields, UTXOData, SendResult } from 'js-1151';
Use these definitions to build typed wrappers in your own codebase or to extend the helpers with framework-specific logic.