npm package: @stratospay/moneygraph-sdk
Description: MoneyGraph SDK - Global payments infrastructure for cross-border transfers, FX, and payouts. AI-native with GitHub Copilot, Amazon Q, Cursor, Windsurf, and Devin support.
Author: MoneyGraph
Latest version: 2.5.0
Deprecated: Deprecated: published in error. Use @moneygraph/sdk instead.

# MoneyGraph SDK

Global payments infrastructure for cross-border transfers, FX, and payouts.

[![npm version](https://img.shields.io/npm/v/moneygraph-sdk.svg)](https://www.npmjs.com/package/moneygraph-sdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

## Features

- Cross-border payouts to 180+ countries
- Real-time FX quotes with rate locking
- Multiple payout rails: ACH, SEPA, Faster Payments, SWIFT, Mobile Money
- KYC/AML compliance built-in
- TypeScript-first with full type safety
- AI coding agent support for GitHub Copilot, Amazon Q, Cursor, Windsurf, and Devin

## Installation

```bash
npm install moneygraph-sdk
```

### AI Agent Setup (Optional)

Copy configuration files for your AI coding assistant:

```bash
# GitHub Copilot - works automatically from node_modules

# Cursor - copy rules to project root
cp node_modules/moneygraph-sdk/.cursorrules .cursorrules
mkdir -p .cursor/rules
cp node_modules/moneygraph-sdk/.cursor/rules/moneygraph.mdc .cursor/rules/

# Windsurf - copy rules to project root  
cp node_modules/moneygraph-sdk/.windsurfrules .windsurfrules

# Amazon Q - copy rules to project
mkdir -p .amazonq
cp node_modules/moneygraph-sdk/.amazonq/rules.md .amazonq/

# Devin - copy wiki to project
mkdir -p .devin
cp node_modules/moneygraph-sdk/.devin/wiki.json .devin/
```

## Quick Start

```typescript
import MoneyGraph from 'moneygraph-sdk';

const mg = new MoneyGraph({ apiKey: process.env.MONEYGRAPH_API_KEY });

// Get FX quote
const quote = await mg.fx.quote({
  source_currency: 'USD',
  destination_currency: 'NGN',
  source_amount: 100
});

// Confirm rate (valid for 2 minutes)
await mg.fx.confirm(quote.id);

// Send payout
const payout = await mg.payouts.create({
  customer_id: 'cust_xxx',
  quote_id: quote.id,
  recipient: {
    name: 'Recipient Name',
    bank_code: '058',
    account_number: '0123456789'
  },
  idempotency_key: `payout-${Date.now()}`
});
```

## Serverless Sandbox

Test instantly without signup using the serverless sandbox:

```typescript
// Use demo key for immediate testing
const mg = new MoneyGraph({ apiKey: 'sk_test_demo' });

// Create pre-verified test customer
const customer = await mg.customers.createMockPersona('business_verified');
// Returns: { id: 'cust_test_xxx', kyc_status: 'APPROVED' }

// Run full payout flow in sandbox
const quote = await mg.fx.quote({ source_currency: 'USD', destination_currency: 'NGN', source_amount: 100 });
await mg.fx.confirm(quote.id);
const payout = await mg.payouts.create({ customer_id: customer.id, quote_id: quote.id, ... });
```

### Mock Personas

| Persona | KYC Status | Use Case |
|---------|------------|----------|
| `business_verified` | APPROVED | Happy path testing |
| `individual_verified` | APPROVED | Consumer flows |
| `pending_kyc` | PENDING | Loading states |
| `rejected_kyc` | REJECTED | Error handling |

## API Keys

### Sandbox Keys (Testing)
Get sandbox keys instantly at [moneygraph.ai](https://moneygraph.ai) or use `sk_test_demo` for quick testing.

### Live Keys (Production)
1. Go to [moneygraph.ai](https://moneygraph.ai)
2. Create an account
3. Complete business verification (KYB)
4. Choose a pricing plan
5. Submit for approval
6. Once approved, live keys (`sk_live_`) available in dashboard

## SDK Methods

### Customers
```typescript
mg.customers.create(params)           // Create customer
mg.customers.list()                   // List customers
mg.customers.retrieve(id)             // Get customer
mg.customers.kyc.submit(id)           // Submit KYC
mg.customers.kyc.uploadDocument(id)   // Upload document
mg.customers.createMockPersona(type)  // Create test customer
```

### Directors (Business Accounts)
```typescript
mg.customers.directors.list(customerId)
mg.customers.directors.create(customerId, params)
mg.customers.directors.update(customerId, directorId, params)
mg.customers.directors.delete(customerId, directorId)
```

### FX
```typescript
mg.fx.quote(params)     // Get quote (2-min expiry)
mg.fx.confirm(quoteId)  // Lock rate
mg.fx.rates()           // Get all rates
```

### Payouts
```typescript
mg.payouts.create(params)              // Bank transfer
mg.payouts.swift.create(params)        // SWIFT wire
mg.payouts.mobileMoney.create(params)  // M-Pesa, MTN
mg.payouts.retrieve(id)                // Get status
```

### Wallets
```typescript
mg.wallets.list(customerId)
mg.wallets.transactions(customerId)
```

### Reference Data
```typescript
mg.reference.countries()
mg.reference.banks.list(countryCode)
mg.reference.mobileNetworks.list(countryCode)
mg.reference.transferPurposes()
mg.reference.sourceOfFunds()
mg.reference.businessRegistrationTypes()
```

### Cards
```typescript
mg.cards.create(params)           // Issue virtual/physical card
mg.cards.retrieve(id)             // Get card details
mg.cards.list(customerId)         // List customer cards
mg.cards.fund(params)             // Fund card from wallet
mg.cards.freeze(id)               // Temporarily block card
mg.cards.unfreeze(id)             // Unblock card
mg.cards.update(id, params)       // Update card settings
mg.cards.cancel(id, params)       // Cancel card permanently
mg.cards.replace(id, params)      // Replace lost/stolen card
mg.cards.transactions(id)         // List card transactions
```

### Crypto
```typescript
mg.crypto.addresses.create(params)      // Generate deposit address
mg.crypto.addresses.list(customerId)    // List deposit addresses
mg.crypto.deposits.list(params)         // List deposits
mg.crypto.deposits.retrieve(id)         // Check deposit status
mg.crypto.settings.update(id, params)   // Enable auto-convert
mg.crypto.convert.quote(params)         // Get conversion quote
mg.crypto.convert.execute(params)       // Execute conversion
mg.payouts.crypto.create(params)        // Send crypto payout
```

### Smart Payout (Auto-Routing)
```typescript
mg.executeSmartPayout({
  customer_id: 'cust_xxx',
  from_currency: 'USD',
  to_currency: 'NGN',
  amount: 100,
  recipient: { ... },
  priority: 'cost' // or 'speed' or 'balanced'
})
```

## Payout Rails

| Country | Rail | Method |
|---------|------|--------|
| USA | ACH | `payouts.create` |
| UK | Faster Payments | `payouts.create` |
| EU | SEPA | `payouts.create` |
| Nigeria | NIP | `payouts.create` |
| Kenya | M-Pesa | `payouts.mobileMoney.create` |
| Ghana | MTN/Vodafone | `payouts.mobileMoney.create` |
| Global | SWIFT | `payouts.swift.create` |

## Critical Rules

1. **Date Format**: Always use `DD-MM-YYYY` (e.g., `15-06-1990`)
2. **KYC Required**: Verify `kyc_status === 'APPROVED'` before payouts
3. **FX Expiry**: Quotes expire in 2 minutes - confirm immediately
4. **Idempotency**: Always include unique `idempotency_key` for payouts
5. **API Prefix**: Use `/customer/` not `/customers/`

## Error Handling

```typescript
import { MoneyGraphError } from 'moneygraph-sdk';

try {
  const payout = await mg.payouts.create(params);
} catch (error) {
  if (error instanceof MoneyGraphError) {
    console.error(`Code: ${error.code}`);
    console.error(`Message: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
  }
}
```

---

## AI Coding Agent Integration

MoneyGraph SDK includes native configuration files for all major AI coding assistants. When you install the SDK, your AI agent automatically learns the correct patterns for payment integrations.

### Supported AI Agents

| Agent | Config File | Status |
|-------|-------------|--------|
| GitHub Copilot | `.github/copilot-instructions.md` | Supported |
| Amazon Q | `.amazonq/rules.md` | Supported |
| Cursor | `.cursorrules` + `.cursor/rules/moneygraph.mdc` | Supported |
| Windsurf | `.windsurfrules` | Supported |
| Devin | `.devin/wiki.json` | Supported |
| Claude | `CLAUDE.md` | Supported |

---

### GitHub Copilot Integration

MoneyGraph SDK provides native GitHub Copilot support through `.github/copilot-instructions.md`. When installed, Copilot understands:

- The Quote -> Confirm -> Payout pattern
- KYC verification requirements before payouts
- Correct SDK namespaces and methods
- Environment variable usage for API keys
- Date format requirements (DD-MM-YYYY)

**Copilot Prompt Examples:**
```
// Ask Copilot: "Create a function to send $100 to Nigeria"
// Ask Copilot: "How do I handle QUOTE_EXPIRED errors?"
// Ask Copilot: "Show me how to create a business customer"
```

**Keywords:** GitHub Copilot payment integration, Copilot fintech SDK, Copilot cross-border payments, AI pair programming payments, GitHub Copilot API integration

---

### Amazon Q Developer Integration

MoneyGraph SDK includes Amazon Q rules in `.amazonq/rules.md` with severity-based compliance enforcement:

**Critical Rules (Severity: ERROR):**
- Never use raw fetch - always use SDK
- Always verify KYC before payouts
- Always use DD-MM-YYYY date format

**Warning Rules (Severity: WARNING):**
- FX quotes expire in 2 minutes
- Use environment variables for API keys
- Include idempotency keys for payouts

**Amazon Q Prompt Examples:**
```
// Ask Q: "Create a compliant payout flow"
// Ask Q: "What's the correct date format for MoneyGraph?"
// Ask Q: "Show me the KYC verification pattern"
```

**Keywords:** Amazon Q payment SDK, Amazon Q Developer fintech, Amazon Q cross-border API, AWS AI coding assistant payments, Amazon Q compliance rules

---

### Cursor IDE Integration

MoneyGraph SDK provides comprehensive Cursor support through two configuration files:

**`.cursorrules`** - Root-level rules with:
- NPM bootstrap prompts
- Serverless sandbox trial workflows
- Mock persona testing examples
- Interactive testing patterns

**`.cursor/rules/moneygraph.mdc`** - MDC format rules with:
- Glob patterns for TypeScript/JavaScript files
- `alwaysApply: true` for automatic activation
- Namespace reference table
- Golden path examples

**Cursor Setup (Required):**

Cursor doesn't automatically read rules from `node_modules`. After installing the SDK, copy the rules to your project:

```bash
# Option 1: Copy .cursorrules to project root
cp node_modules/moneygraph-sdk/.cursorrules .cursorrules

# Option 2: Copy MDC rules (recommended for Cursor 2.1+)
mkdir -p .cursor/rules
cp node_modules/moneygraph-sdk/.cursor/rules/moneygraph.mdc .cursor/rules/

# Option 3: Copy both for maximum compatibility
cp node_modules/moneygraph-sdk/.cursorrules .cursorrules
mkdir -p .cursor/rules
cp node_modules/moneygraph-sdk/.cursor/rules/moneygraph.mdc .cursor/rules/
```

**Cursor Quick Start:**
```typescript
// Say "setup moneygraph" - Cursor installs and initializes
// Say "test moneygraph sandbox" - Cursor creates full trial flow
// Say "create payout to Kenya" - Cursor generates M-Pesa code
```

**Cursor Chat Examples:**
```
// Ask Cursor: "What's the difference between payouts.create and payouts.swift.create?"
// Ask Cursor: "How do I test without a real API key?"
// Ask Cursor: "Show me the mock persona options"
```

**Keywords:** Cursor IDE payment integration, Cursor fintech SDK, Cursor MDC rules payments, Cursor AI coding payments, Cursor cross-border transfers

---

### Windsurf IDE Integration

MoneyGraph SDK supports Windsurf (Codeium) through `.windsurfrules` with Cascade-style rules:

**Windsurf Features:**
- Cascade-compatible rule format
- Namespace mapping for all SDK methods
- Compliance patterns for KYC and FX
- Error handling templates

**Windsurf Prompt Examples:**
```
// Ask Windsurf: "Build a remittance flow to Nigeria"
// Ask Windsurf: "Create a mobile money payout to Kenya"
// Ask Windsurf: "Show me SWIFT transfer setup"
```

**Keywords:** Windsurf payment SDK, Windsurf fintech integration, Codeium payment API, Windsurf cross-border SDK, Windsurf AI coding payments

---

### Devin AI Integration

MoneyGraph SDK supports Devin autonomous coding through `.devin/wiki.json`:

**Wiki.json Structure:**
- Domain mappings for payment concepts
- Recipe references for common flows
- Compliance requirements documentation
- Test data and mock personas

**Devin Task Examples:**
```
"Build a complete remittance integration using MoneyGraph SDK"
"Create a KYC verification flow with document upload"
"Implement multi-rail payout routing based on destination"
```

**Keywords:** Devin AI payment integration, Devin autonomous coding payments, Devin fintech SDK, Devin cross-border API, AI software engineer payments

---

### Claude AI Integration

MoneyGraph SDK includes `CLAUDE.md` for Claude-powered applications:

**Claude Features:**
- Complete API reference
- Code examples for all endpoints
- Error handling patterns
- Compliance requirements

**Claude Tool Schemas:**
```typescript
import { claudeTools } from 'moneygraph-sdk';

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  messages: [...],
  tools: claudeTools
});
```

**Keywords:** Claude AI payment SDK, Anthropic Claude fintech, Claude tool calling payments, Claude API integration, Claude cross-border transfers

---

### OpenAI / GPT Integration

MoneyGraph SDK provides OpenAI function calling schemas:

```typescript
import { openAITools } from 'moneygraph-sdk';

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [...],
  tools: openAITools
});
```

**Keywords:** OpenAI payment SDK, GPT function calling payments, ChatGPT fintech integration, OpenAI cross-border API, GPT-4 payment tools

---

## TypeScript Support

Full TypeScript support with exported types:

```typescript
import type {
  Customer,
  CustomerCreateParams,
  Payout,
  PayoutCreateParams,
  FXQuote,
  Director,
  Wallet,
  Transaction,
  MoneyGraphError
} from 'moneygraph-sdk';
```

## Environment Variables

```bash
# .env
MONEYGRAPH_API_KEY=sk_test_...  # or sk_live_... for production
```

## Links

- Website: [moneygraph.ai](https://moneygraph.ai)
- Documentation: [docs.moneygraph.ai](https://docs.moneygraph.ai)
- API Reference: [moneygraph.ai/docs/api](https://moneygraph.ai/docs/api)
- Support: support@moneygraph.ai

## License

MIT

---

## SEO Keywords

MoneyGraph SDK, cross-border payments API, international money transfer SDK, FX API, foreign exchange SDK, payout API, remittance SDK, ACH payments, SEPA transfers, Faster Payments API, SWIFT API, mobile money SDK, M-Pesa integration, MTN Mobile Money, fintech SDK, payment infrastructure, TypeScript payment SDK, Node.js payment API, AI payment integration, GitHub Copilot payments, Amazon Q fintech, Cursor payment SDK, Windsurf payments, Devin AI payments, Claude payment tools, OpenAI payment functions, GPT payment integration, KYC API, AML compliance SDK, multi-currency wallets, global payouts, Nigeria payments, Kenya payments, Africa payments, emerging markets payments, B2B payments, B2C payments, payment orchestration, payment rails, real-time payments