@moneygraph/sdk v3.0.0

Global cross-border payment SDK powered by StratosPay. Send payouts to 82+ countries, collect payments, swap currencies, and track everything on-chain.

Install

npm install @moneygraph/sdk

Quick Start

Production (API Key)

import { MoneyGraphClient } from '@moneygraph/sdk';

const mg = new MoneyGraphClient({ apiKey: 'sk_live_...' });

// Create customer → Submit KYC → Create recipient → Send payout
const customer = await mg.createCustomer({
  first_name: 'John', last_name: 'Doe',
  email: 'john@example.com', phone: '2025551234',
  phone_iso2: 'US', country: 'US'
});

await mg.submitKyc(customer.data.id);

// Get corridor config (rates, delivery windows, fees)
const currencies = await mg.getCurrencies('US');
const usd = currencies.find(c => c.currency === 'USD');
const corridor = usd.settings.international_remittance.find(c => c.iso2 === 'NG');
const window = usd.settings.delivery_windows[0];

// Create recipient (step 1)
const recipient = await mg.createRecipient({
  international_remittance_id: corridor.id,
  first_name: 'Friday', last_name: 'Okoro',
  email: 'friday@example.ng', phone: '8012345678', phone_iso2: 'NG',
  delivery_method: 'bank', entity_type: 'personal',
  routing_type: 'SWIFT', routing_code: 'GTBINGLA',
  acct_no: '0123456789', acct_name: 'Friday Okoro'
});

// Create payout (step 2) — amount in minor units (100000 = 1,000.00)
const wallets = await mg.listWallets();
const payout = await mg.createPayout({
  wallet_id: wallets.data[0].id,
  account_id: customer.data.id,
  recipient_id: recipient.data.id,
  delivery_window_id: window.id,
  amount: 100000
});

Sandbox (No API Key Needed)

import { MoneyGraphSandbox } from '@moneygraph/sdk';

const mg = new MoneyGraphSandbox();
// Same API as MoneyGraphClient — all methods available
// KYC auto-approves, payouts can be simulated
await mg.simulatePayoutSuccess(payout.data.id);

Convenience Helpers

// One-call bank payout (creates recipient + payout)
const result = await mg.sendBankPayout({
  customerId: '0605399',
  walletId: 'uuid-...',
  corridorId: 'uuid-...',
  deliveryWindowId: 'uuid-...',
  transferPurposeId: 'uuid-...',
  amount: 100000,
  recipientFirstName: 'Friday',
  recipientLastName: 'Okoro',
  recipientEmail: 'friday@example.ng',
  recipientPhone: '8012345678',
  recipientPhoneIso2: 'NG',
  bankName: 'GTBank',
  routingType: 'SWIFT',
  routingCode: 'GTBINGLA',
  acctNo: '0123456789',
  acctName: 'Friday Okoro'
});

API Coverage (55 endpoints)

Category	Endpoints	Methods
Customers	10	createCustomer, createBusinessCustomer, updateCustomer, listCustomers, getCustomer, submitKyc, uploadKycDocument, getCustomerWallets, getCustomerTransactions, getCustomerTransaction
Directors (KYB)	5	listDirectors, getDirector, createDirector, updateDirector, deleteDirector
Reference	7	listCountries, getCurrencies, listSourceOfFunds, listMccCodes, listBusinessRegistrationTypes, listWallets, swapFunds
Local Transfers	2	transferToCustomer, transferFromCustomer
Payment Collection	2	initiatePayment, verifyPayment
Recurring	5	createPlan, getPlan, listPlans, updatePlan, deletePlan
Transactions	4	listTransactions, getTransaction, getRecipientTransactions, getWalletTransactions
Recipients	5	createRecipient, getRecipient, listRecipients, updateRecipient, deleteRecipient
Payouts	7	createPayout, verifyBank, listTransferPurposes, listMobileNetworks, listCashPickupAgents, simulatePayoutSuccess, simulatePayoutDecline
Blockchain Ledger	8	createLedgerEntity, getLedgerEntity, listLedgerEntities, ledgerCredit, ledgerDebit, ledgerTransfer, getLedgerTransaction, getLedgerTransactions

Key Concepts

Two-Step Payout Flow: Always create a Recipient first, then create a Payout referencing that recipient. The getCurrencies() call provides all required UUIDs.

Amount in Minor Units: All amounts are in minor units. 100000 = 1,000.00. The API returns both amount (minor) and human_readable_amount (decimal).

Customer IDs: Numeric strings like "0605399" (not prefixed IDs).

UUID References: wallet_id, recipient_id, corridor_id, delivery_window_id are all UUIDs from the API.

Base Currencies & Rails

Currency	Rails	Corridors
USD	ACH, Wire, SWIFT	82 countries
GBP	Faster Payments, SWIFT	82 countries
EUR	SEPA, BACS, SWIFT	82 countries
CAD	SWIFT	82 countries

Claude / AI Agent Integration

import { MONEYGRAPH_SYSTEM_PROMPT, MONEYGRAPH_TOOLS } from '@moneygraph/sdk/claude';

// Use with Anthropic API
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  system: MONEYGRAPH_SYSTEM_PROMPT,
  tools: MONEYGRAPH_TOOLS,
  messages: [{ role: 'user', content: 'Send $500 to Nigeria' }]
});

Rate Data (Sandbox)

import { SWAP_RATES, PAYOUT_RATES, REMITTANCE_CORRIDORS } from '@moneygraph/sdk/rates';

// 328 real rate pairs across 4 base currencies
console.log(PAYOUT_RATES.USD.NG); // { c: 'NGN', r: 1602.34 }
console.log(SWAP_RATES.USD.rates.GBP); // 0.7455

Response Format

Single entities return { message, status, data }. Lists return Laravel-style pagination with { data, links, meta }.

Rate Limit

30 requests/minute. Pass onRateLimit callback to get warnings:

const mg = new MoneyGraphClient({
  apiKey: 'sk_...',
  onRateLimit: ({ remaining }) => console.warn(`Rate limit: ${remaining} left`)
});

License

MIT