@1money/1money-ts-sdk

TypeScript SDK for the 1Money Stablecoin Platform API.

Features

• Full coverage of all 1Money API endpoints
• ESM and CommonJS dual-package support
• HMAC-SHA256 request signing for production, Bearer token for sandbox
• Idempotency key support for critical operations
• Full TypeScript type definitions
• Node.js 18+

Installation

npm install @1money/1money-ts-sdk

Quick Start

import { OneMoneySDK } from "@1money/1money-ts-sdk";

const sdk = new OneMoneySDK({
  accessKey: process.env.ONEMONEY_ACCESS_KEY!,
  secretKey: process.env.ONEMONEY_SECRET_KEY!,
  sandbox: true,
});

// List customers
const customers = await sdk.customers.list({ page_size: 10 });
console.log(customers);

Or load configuration from environment variables automatically:

const sdk = OneMoneySDK.fromConfig();

Configuration

| Parameter | Type | Required | Default | Description | | ----------- | --------- | -------- | ------------------------------------ | ---------------------------- | | accessKey | string | Yes | — | API access key | | secretKey | string | Yes | — | API secret key | | sandbox | boolean | No | true | Use sandbox environment | | baseUrl | string | No | https://api.sandbox.1money.com | API base URL | | timeoutMs | number | No | 30000 | Request timeout (ms) |

Environment Variables

| Variable | Description | | --------------------- | ----------------- | | ONEMONEY_ACCESS_KEY | API access key | | ONEMONEY_SECRET_KEY | API secret key | | ONEMONEY_BASE_URL | API base URL override |

Services

Customers

// List
const list = await sdk.customers.list({ page_size: 10, page_num: 1 });

// Create
const customer = await sdk.customers.create({
  business_name: "Acme Corp",
  email: "[email protected]",
  business_type: "corporation",
  industry: "technology",
});

// Get / Update
const detail = await sdk.customers.get(customerId);
const updated = await sdk.customers.update(customerId, { business_name: "New Name" });

// Associated Persons
await sdk.customers.createAssociatedPerson(customerId, { first_name: "Alice", last_name: "Wang", email: "[email protected]" });
await sdk.customers.listAssociatedPersons(customerId);
await sdk.customers.getAssociatedPerson(customerId, personId);
await sdk.customers.updateAssociatedPerson(customerId, personId, { first_name: "Bob" });
await sdk.customers.deleteAssociatedPerson(customerId, personId);

// Intermediaries
await sdk.customers.createIntermediary(customerId, { name: "Partner Bank", type: "bank" });
await sdk.customers.listIntermediaries(customerId);
await sdk.customers.updateIntermediary(customerId, intermediaryId, { name: "New Name" });
await sdk.customers.deleteIntermediary(customerId, intermediaryId);

// TOS Link
const tosLink = await sdk.customers.createTosLink({ customer_id: customerId });

Assets

const assets = await sdk.assets.getAll(customerId);

External Accounts

await sdk.externalAccounts.list(customerId);
await sdk.externalAccounts.create(customerId, { idempotency_key: key, type: "bank_account", currency: "USD" });
await sdk.externalAccounts.getById(customerId, accountId);
await sdk.externalAccounts.getByIdempotencyKey(customerId, key);
await sdk.externalAccounts.remove(customerId, accountId);

Recipients

// Recipients
await sdk.recipients.list(customerId, { page_size: 10 });
await sdk.recipients.create(customerId, { idempotency_key: key, name: "John Doe", type: "individual" });
await sdk.recipients.get(customerId, recipientId);
await sdk.recipients.update(customerId, recipientId, { name: "Jane Doe" });
await sdk.recipients.delete(customerId, recipientId);

// Bank Accounts
await sdk.recipients.addBankAccount(customerId, recipientId, { idempotency_key: key, currency: "USD", account_number: "123456789", routing_number: "021000021" });
await sdk.recipients.listBankAccounts(customerId, recipientId);
await sdk.recipients.updateBankAccount(customerId, recipientId, bankAccountId, { account_number: "987654321" });
await sdk.recipients.deleteBankAccount(customerId, recipientId, bankAccountId);

Conversions

// Create a quote
const quote = await sdk.conversions.createQuote(customerId, {
  from_asset: { asset: "USDC", network: "ethereum", amount: "100" },
  to_asset: { asset: "USD", network: "ach" },
});

// Lock in the quote
const hedge = await sdk.conversions.createHedge(customerId, { quote_id: quote.quote_id });

// Get conversion order
const order = await sdk.conversions.getOrder(customerId, orderId);

Transfers

const transfer = await sdk.transfers.create(customerId, {
  idempotency_key: key,
  target_customer_id: "cus_target_id",
  asset: "USDC",
  amount: "10",
  description: "Payment",
});
await sdk.transfers.get(customerId, transactionId);
await sdk.transfers.getByIdempotencyKey(customerId, key);

Withdrawals

const withdrawal = await sdk.withdrawals.create(customerId, {
  idempotency_key: key,
  target_customer_id: "cus_target_id",
  asset: "USDC",
  amount: "50",
});
await sdk.withdrawals.get(customerId, transactionId);
await sdk.withdrawals.getByIdempotencyKey(customerId, key);

Auto Conversion Rules

await sdk.autoConversionRules.list(customerId, { page_size: 10 });
await sdk.autoConversionRules.create(customerId, { idempotency_key: key, from_asset: "USDC", to_asset: "USD" });
await sdk.autoConversionRules.getById(customerId, ruleId);
await sdk.autoConversionRules.getByIdempotencyKey(customerId, key);
await sdk.autoConversionRules.delete(customerId, ruleId);

// Orders
await sdk.autoConversionRules.listOrders(customerId, ruleId);
await sdk.autoConversionRules.getOrderById(customerId, ruleId, orderId);

Deposit Instructions

const instructions = await sdk.depositInstructions.get(customerId, {
  asset: "USDC",
  network: "ethereum",
});

Fees

const fee = await sdk.fees.estimate(customerId, {
  action: "withdrawal",
  asset: "USDC",
  network: "ethereum",
  amount: "100",
});

Transactions

const transactions = await sdk.transactions.list(customerId, { page_size: 5 });
const tx = await sdk.transactions.get(customerId, transactionId);

Simulations (Sandbox Only)

const simulation = await sdk.simulations.simulateDeposit(customerId, {
  asset: "USDC",
  network: "ethereum",
  amount: "1000",
});

Error Handling

All API errors are thrown as ApiError instances:

import { OneMoneySDK, ApiError } from "@1money/1money-ts-sdk";

try {
  await sdk.customers.get("cus_nonexistent");
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.status);   // HTTP status code (e.g. 404)
    console.log(err.code);     // Error code string
    console.log(err.detail);   // Detailed error message
    console.log(err.instance); // Request instance identifier
  }
}

Examples

Run any example with:

ONEMONEY_ACCESS_KEY=your_key ONEMONEY_SECRET_KEY=your_secret npx tsx examples/basic-usage.ts

| Example | Description | | -------------------------------- | ------------------------------------ | | basic-usage.ts | SDK initialization and common APIs | | customers.ts | Customer CRUD, persons, intermediaries | | conversions.ts | Quotes, hedges, conversion orders | | transfers-and-withdrawals.ts | Transfers and withdrawals | | recipients.ts | Recipients and bank accounts | | external-accounts.ts | External account management | | auto-conversion-rules.ts | Auto conversion rule CRUD | | deposits-and-simulations.ts | Deposit instructions and simulations | | error-handling.ts | Error handling patterns |

Authentication

• Sandbox (sandbox: true): Uses Bearer token authentication with accessKey.
• Production (sandbox: false): Uses HMAC-SHA256 request signing with both accessKey and secretKey.

Development

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

# Clean build output
npm run clean

License

MIT