@moneygraph/sdk/CLAUDE_AI_INSTRUCTIONS.md

AI-native SDK for global payouts powered by StratosPay

# MoneyGraph SDK - Claude.ai Project Instructions

Use this file as Project Instructions when building payment applications in Claude.ai Projects.

---

## Copy This Entire Section Into Claude.ai Project Instructions

```
You are helping build a payment application using the MoneyGraph SDK, which wraps the StratosPay API.

## SDK Overview

MoneyGraph provides:
- Customer onboarding & KYC
- FX quotes & currency conversion
- International payouts (107+ currencies)
- Payment acceptance (cards, widgets)
- Wallet management

## CRITICAL RULES - MEMORIZE THESE

### 1. KYC Before Payouts (MANDATORY)
Customers MUST have approved KYC before sending payouts. Always check:
```typescript
const { allowed, status } = await mg.onboard.canPayout(customerId);
if (!allowed) throw new Error(`KYC ${status}`);
```

### 2. Quote & Confirm Pattern
FX quotes expire in 2 MINUTES. Always:
1. Get quote → Show user
2. User confirms → Lock rate
3. Execute payout

```typescript
const quote = await mg.liquidity.getQuote({ from: 'USD', to: 'NGN', amount: 100 });
// Show rate to user, on confirm:
await mg.liquidity.confirmQuote(quote.id);
await mg.payouts.send({ quote_id: quote.id, ... });
```

### 3. Date Format
ALWAYS use DD-MM-YYYY for birthday and dates:
```typescript
birthday: '29-06-1999'  // ✓ Correct
birthday: '1999-06-29'  // ✗ Wrong - will fail
```

### 4. API Mode Detection
SDK auto-detects mode from API key:
- `sk_test_*` → Sandbox (mock data)
- `sk_live_*` → Production (real money!)

## SDK Structure

```typescript
import { MoneyGraph } from '@moneygraph/sdk';

const mg = new MoneyGraph({ apiKey: 'sk_test_xxx' });

mg.onboard       // Customers, KYC, Directors, Wallets
mg.liquidity     // FX quotes
mg.payouts       // Send money
mg.reference     // Countries, currencies, banks, etc.
mg.payments      // Accept payments (cards)
mg.remittance    // Sender→Recipient→Transaction model
```

## Common Patterns

### Create Customer
```typescript
const customer = await mg.onboard.createCustomer({
  account_type: 'personal',  // or 'business'
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  phone: '1234567890',
  phone_iso2: 'US',
  country: 'US',
});
```

### Complete KYC
```typescript
await mg.onboard.updateCustomer(customerId, {
  birthday: '15-03-1990',  // DD-MM-YYYY!
  gender: 'male',
  id_type: 'PASSPORT',  // PASSPORT | DRIVERS | NATIONAL_ID
  id_number: 'AB1234567',
  source_of_fund_id: 'uuid-from-reference',
  state: 'CA',
  city: 'Los Angeles',
  street: '123 Main St',
  postal_code: '90001',
});

await mg.onboard.submitKyc(customerId);
```

### Send Payout (Complete Flow)
```typescript
// All-in-one helper
const payout = await mg.sendPayout({
  customerId: 'cust_123',
  from: 'USD',
  to: 'NGN',
  amount: 100,
  recipient: {
    name: 'Jane Doe',
    bank_code: '058',
    account_number: '0123456789',
  },
});
```

### Accept Payment (Widget)
```html
<script src="https://stratospay.com/popup.js"></script>
<script>
checkout.init({
  public_key: "pk_test_xxx",
  external_reference: `order_${Date.now()}`,
  amount: 9900,  // $99.00 in cents
  currency: "USD",
  customer: { email, first_name, last_name, ip_address },
  billing_address: { country, city, address, postal_code },
  onsuccess: (data) => console.log('Paid!', data),
  onerror: (err) => console.error('Failed', err),
});
</script>
```

## Error Handling
```typescript
import { MoneyGraphError } from '@moneygraph/sdk';

try {
  await mg.payouts.send(params);
} catch (error) {
  if (error instanceof MoneyGraphError) {
    switch (error.code) {
      case 'KYC_PENDING': // Complete verification
      case 'KYC_REJECTED': // Contact support
      case 'QUOTE_EXPIRED': // Refresh quote
      case 'INSUFFICIENT_BALANCE': // Add funds
      case 'VALIDATION_ERROR': // Check inputs
    }
  }
}
```

## Testing (Sandbox)
```typescript
// Create instant verified customers
const customer = await mg.onboard.createMockPersona('business_verified');
// Options: 'business_verified', 'individual_verified', 'pending_kyc', 'rejected_kyc'
```

## Test Cards
- Success: 4917484589897107
- Insufficient funds: 6011111111111117
- Requires 3DS: 4263982640269299

## Reference Data Methods
```typescript
mg.reference.getCountries()
mg.reference.getCurrencies('US')
mg.reference.getBanks('NG')
mg.reference.getSourceOfFunds()
mg.reference.getMccCodes()
mg.reference.getBusinessRegistrationTypes()
mg.reference.getTransferPurposes()
```

## Supported Currencies
- Pay-in: USD, EUR, NGN, KES, GHS + crypto (USDC, USDT, ETH, BTC)
- Payout: 107+ including NGN, KES, ZAR, INR, PHP, MXN, BRL, EUR, GBP

## CORS Warning
The SDK cannot be used directly from browser. Use a backend proxy:
- Supabase Edge Function
- Next.js API route
- Express server
```

---

## Additional Context for Complex Projects

If building a full remittance app, also include:

```
## Remittance Flow (Sender → Recipient → Transaction)

For international transfers:
1. Create Sender (your customer with KYC)
2. Look up corridor restrictions (currency_id, delivery methods)
3. Create Recipient (bank, mobile_money, or cash_pickup)
4. Get Quote → Confirm Quote
5. Create Transaction with international_remittance_id
6. Monitor status via webhooks

## Key IDs to Track
- currency_id: Target currency UUID
- transfer_purpose_id: Compliance requirement
- international_remittance_id: Specific corridor
- delivery_window_id: Speed option
- bank_id / mobile_network_id: Delivery details

## Fee Structure
Total = Delivery Fee + Method Fee + (Amount × Swap Rate)
Fee types: no_fee, fiat, percent, fiat_percent
```

---

## How to Use This File

1. Create a new Project in Claude.ai
2. Click "Edit Project Instructions"
3. Copy the content between the ``` markers above
4. Paste into Project Instructions
5. Add relevant recipe files to Project Knowledge if needed

Claude will now understand MoneyGraph SDK patterns and help you build payment features correctly.