Install the SDK

Getting Started

This guide explains how to get started with the SuiPay TypeScript SDK for accepting cryptocurrency payments and managing withdrawals.

Installation

Install the SuiPay SDK using npm or yarn:

npm install @suipay/api
# or
yarn add @suipay/api

Requirements

• Node.js 16.0.0 or higher

• TypeScript 4.5 or higher (for TypeScript projects)

Quick Start

1. Get Your API Key

Before using the SDK, you'll need an API key from the SuiPay dashboard:

1. Login to SuiPay: Visit https://demo2.suipay.net and sign in to your account

2. Navigate to Dev API Keys: Go to the "Dev API Keys" section in your dashboard

3. Create New API Key: Click the "Create API Key" button

4. Name Your Key: Give your API key a descriptive name (e.g., "Production API", "Development Testing")

5. Save the Key: Your API key will be displayed once. Copy and store it securely - you won't be able to see it again!

Important: API keys start with sk_ and should be kept secure. Never share them publicly or commit them to version control.

Your API key will look like this:

sk_1234567890abcdef1234567890abcdef

API Key Security Best Practices:

• Store API keys as environment variables

• Never commit API keys to version control

• Rotate API keys regularly

• Delete unused API keys from your dashboard

2. Initialize the Client

Import and initialize the SuiPay client:

import { SuiPayClient } from '@suipay/api';

const client = new SuiPayClient({
  apiKey: 'sk_your_api_key_here',
  // baseUrl: 'https://api.suipay.net/api/v1' // optional, defaults to production
});

3. Test Your Connection

Verify your API key and connection:

const result = await client.ping();
if (result.success) {
  console.log(`Connected successfully! User ID: ${result.user_id}`);
} else {
  console.log('Connection failed - check your API key');
}

4. Get User Information

Retrieve your user information and current balance:

const user = await client.user.get();
console.log(`Balance: ${user.polar_balance_usdc} USDC`);
console.log(`KYC Complete: ${user.kyc_complete}`);

5. Create a Payment Link

Create a payment link that customers can use to pay you:

import { PaymentDestinationType } from '@suipay/api';

const paymentLink = await client.paymentLinks.create({
  amount_usdc: 50.00,
  description: 'Test payment',
  destination_type: PaymentDestinationType.POLAR_BALANCE
});

console.log(`Payment URL: ${paymentLink.url}`);

Environment Configuration

You can configure the SDK using environment variables:

# .env file
SUIPAY_API_KEY=sk_your_api_key_here
SUIPAY_API_URL=https://api.suipay.net/api/v1  # optional

Then use in your code:

const client = new SuiPayClient({
  apiKey: process.env.SUIPAY_API_KEY!,
  baseUrl: process.env.SUIPAY_API_URL, // optional
  timeout: 30000 // optional, request timeout in ms (default: 30000)
});

Error Handling

The SDK provides specific error types for different scenarios:

import { 
  SuiPayValidationError, 
  SuiPayAuthenticationError,
  SuiPayRateLimitError,
  SuiPayServerError 
} from '@suipay/api';

try {
  const user = await client.user.get();
} catch (error) {
  if (error instanceof SuiPayAuthenticationError) {
    console.error('Authentication failed - check your API key');
  } else if (error instanceof SuiPayRateLimitError) {
    console.error('Rate limit exceeded - please wait before retrying');
  } else if (error instanceof SuiPayValidationError) {
    console.error('Validation error:', error.response?.error);
  } else if (error instanceof SuiPayServerError) {
    console.error('Server error:', error.status, error.message);
  }
}

Rate Limits

The SuiPay API has the following rate limits:

• General API endpoints: 300 requests per minute

• Authentication endpoints: 5 requests per minute

The SDK will automatically throw a SuiPayRateLimitError when rate limits are exceeded.

Next Steps

• Learn more about authentication configuration

• Understand how to work with users and their data

• Create and manage payment links

• Implement withdrawal functionality

• Handle errors properly