npm package: @sky-mavis/flow-cash-sdk
Description: A simple SDK for deposit today, cash out tomorrow.
Latest version: 0.1.1

# @sky-mavis/flow-cash-sdk

A TypeScript SDK for deposit (on-ramp) and withdrawal (off-ramp) flows in the Ronin Wallet ecosystem. Integrates **Onramper**, **Binance Connect**, **Relay**, and **Neo Wallet**.

> 📄 **[Full SDK Documentation](docs/SDK_DOCUMENTATION.md)** — Scope, architecture, API reference, and flows.

## Installation

```bash
yarn add @sky-mavis/flow-cash-sdk
# or
npm install @sky-mavis/flow-cash-sdk
```

## Usage Flow

The deposit flow consists of 3 simple steps:

### Step 1: Get Form Data (Defaults, Currencies, Payment Methods)

```typescript
import { DepositService } from '@sky-mavis/flow-cash-sdk';

const depositService = new DepositService({
  // Optional overrides
  // relayApiUrl: 'https://api.relay.link',
  // onramperApiUrl: 'https://api.onramper.com',
  // onramperApiKey: '<ONRAMPER_PUBLIC_KEY>',
  // neoWalletApiUrl: 'https://wallet-manager-stg.skymavis.one/neo-wallet/v1',
  // privyToken: '<PRIVY_TOKEN>',
});

// Get recommended defaults
const defaults = await depositService.getDefaults({ type: 'buy' });
const { amount, source, paymentMethod } = defaults.recommended;

// Get available currencies
const currencies = await depositService.getCurrencies();

// Get available payment methods
const paymentMethods = await depositService.getPaymentTypes({
  source: 'vnd',
  destination: 'usdc_base',
  type: 'buy',
});
```

### Step 2: Get Quotes (Onramper + Relay)

```typescript
// Get quotes from Onramper
const quotes = await depositService.getQuotes({
  crypto: 'usdc_base',
  fiat: 'vnd',
  amount: '1000000',
  user: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  paymentMethod: 'momo',
  useDepositAddress: true, // Enable relay for cross-chain deposit
  fromToken: {
    chainId: 8453, // Base
    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
    decimals: 6,
  },
  toToken: {
    chainId: 2020, // Ronin
    address: '0x0b7007c13325c48911f73a2dad5fa5dcbf808adc', // USDC on Ronin
    decimals: 6,
  },
});

// Select a quote
const selectedQuote = quotes[0];

// Get relay quote for deposit address
const relayQuote = await selectedQuote.getRelayQuote?.();
const depositAddress = relayQuote?.steps[0].depositAddress;
```

### Step 3: Initiate Checkout

```typescript
// Initiate checkout
const checkout = await depositService.initiateCheckout({
  ramp: selectedQuote.ramp,
  source: 'vnd',
  destination: 'usdc_base',
  amount: 1000000,
  type: 'buy',
  paymentMethod: 'momo',
  network: 'base',
  quoteId: selectedQuote.quoteId,
  addresses: {
    evm: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  },
});

// Open checkout URL
window.open(checkout.transactionInformation.url, '_blank');
```

### Optional: Sell Quotes (Offramp + Relay)

```typescript
const { onramperQuotes, relayQuote } = await depositService.getSellQuotes({
  crypto: 'usdc_base',
  fiat: 'vnd',
  amount: '1000000',
  user: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  paymentMethod: 'momo',
  type: 'sell',
  useRelay: true,
  fromToken: {
    chainId: 2020, // Ronin
    address: '0x0b7007c13325c48911f73a2dad5fa5dcbf808adc',
    decimals: 6,
  },
  toToken: {
    chainId: 8453, // Base
    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    decimals: 6,
  },
});
```

### Optional: Neo Wallet Checkout (Privy)

```typescript
const depositService = new DepositService({
  neoWalletApiUrl: 'https://wallet-manager-stg.skymavis.one/neo-wallet/v1',
  privyToken: '<PRIVY_TOKEN>',
});

const checkout = await depositService.neoWalletInitiateCheckout({
  ramp: selectedQuote.ramp,
  source: 'vnd',
  destination: 'usdc_base',
  amount: 1000000,
  type: 'buy',
  paymentMethod: 'momo',
  network: 'base',
  quoteId: selectedQuote.quoteId,
  relayRequestId: relayQuote?.requestId,
  addresses: {
    evm: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  },
});

window.open(checkout.transactionInformation.url, '_blank');
```

## Project Structure

```
src/
├── index.ts              # Main entry point - public API
└── deposit/
    ├── constants.ts      # API URLs, defaults, USDC_TOKENS
    ├── services/         # External API integrations
    │   ├── index.ts      # DepositService
    │   ├── onramper.ts
    │   ├── relay.ts
    │   ├── neo-wallet.ts
    │   └── binance-connect.ts
    ├── types/            # TypeScript types
    │   ├── index.ts
    │   ├── client.ts
    │   ├── config.ts
    │   ├── onramper.ts
    │   ├── relay.ts
    │   ├── neo-wallet.ts
    │   └── binance-connect.ts
    └── utils.ts          # Helper functions
```

## Development

```bash
# Install dependencies
yarn install

# Build
yarn build

# Development mode with watch
yarn dev

# Lint
yarn lint

# Type check
yarn typecheck
```

## Architecture

- **`services/`** - External API integrations and `DepositService`
- **`types/`** - All TypeScript type definitions
- **`constants.ts`** - API URLs and default values
- **`utils.ts`** - Pure utility functions (validation, formatting)

## License

MIT