Quickstart - Rise B2B API

Welcome to Rise B2B API! This guide will help you integrate with our blockchain-based global payroll platform in minutes.

Fast Setup

Configure authentication and execute your first API call in under 5 minutes

Secure by Default

Built on blockchain with SIWE authentication and EIP-712 signing

Global Reach

Support for 190+ countries and 90+ local currencies

Crypto Ready

Process payments in 100+ cryptocurrencies and stablecoins

Prerequisites

Before beginning your integration, ensure you have:

A Rise account with a RiseID (get one at app.riseworks.io)
Node.js installed (version 16 or higher)
Basic knowledge of JavaScript/TypeScript

New to blockchain? No concerns! You can use a private key from your wallet to authenticate with Rise, or use a JWT token. A private key functions as a digital signature that verifies wallet ownership, which connects to your Rise account. Learn more about how wallets work and authentication methods.

Step 1: Configure Your Environment

First, create a new project and install the Rise SDK:

mkdir rise-b2b-integration
cd rise-b2b-integration
npm init -y
npm install @riseworks/sdk dotenv

Create a .env file for your configuration:

# Environment (optional - defaults to 'prod')
RISE_ENVIRONMENT=prod  # or 'stg' for staging

# Your Rise credentials
RISE_ID=rise_your_rise_id_here
WALLET_PRIVATE_KEY=your_private_key_here

# Alternative: JWT token (if you have one)
# JWT_TOKEN=your_jwt_token_here

Need help with authentication? Review our Private Keys Guide for step-by-step instructions on how to retrieve your private key from MetaMask, hardware wallets, or generate a new one. You can also learn about how wallets work and authentication methods.

Security Note: Never commit your .env file to version control. Your private key gives full access to your wallet. Store it securely and use environment variables in production.

Step 2: Initialize the Rise SDK

Create your first integration script:

// quickstart.js
require('dotenv').config();
const { RiseApiClient } = require('@riseworks/sdk');

// Initialize the Rise API client with your credentials
const client = new RiseApiClient({
  environment: process.env.RISE_ENVIRONMENT || 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

// Alternative: Initialize with JWT token
// const client = new RiseApiClient({
//   environment: process.env.RISE_ENVIRONMENT || 'prod',
//   jwtToken: process.env.JWT_TOKEN
// });

async function main() {
  try {
    console.log('🚀 Starting Rise B2B API integration...\n');

    // The SDK automatically handles authentication
    console.log('Authenticating with Rise...');
    
    // Retrieve current user information
    const user = await client.me.get();
    console.log('User authenticated:', user.data.name);
    console.log('User Rise ID:', user.data.riseid);

    // Retrieve user's companies
    console.log('\n📊 Fetching user companies...');
    const companies = await client.user.getCompanies();
    console.log('Companies:', companies.data.companies.length);

    // Retrieve user's teams
    console.log('\n👥 Fetching user teams...');
    const teams = await client.user.getTeams();
    console.log('Teams:', teams.data.teams.length);

    // Get entity balance (replace with actual nanoid)
    if (companies.data.companies.length > 0) {
      const companyNanoid = companies.data.companies[0].nanoid;
      console.log(`\n💰 Fetching balance for company: ${companyNanoid}`);
      
      const balance = await client.entityBalance.get({
        nanoid: companyNanoid
      });
      console.log('Balance:', balance.data);
    }

    console.log('\n🎉 Integration test completed successfully!');

  } catch (error) {
    console.error('\n💥 Integration test failed:', error.message);
    process.exit(1);
  }
}

main();

Step 3: Execute Your Integration

Execute your integration:

node quickstart.js

Step 4: Advanced SDK Usage

Here are additional examples using the Rise SDK:

// advanced-examples.js
require('dotenv').config();
const { RiseApiClient } = require('@riseworks/sdk');

const client = new RiseApiClient({
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

async function advancedExamples() {
  try {
    // 1. Execute a payment using the SDK
    console.log('💳 Processing payment...');
    const payment = await client.payments.sendPayment({
      team_nanoid: 'your_team_nanoid',
      payments: [
        {
          recipient_nanoid: 'recipient_nanoid',
          amount: '100.00',
          currency: 'USD',
          description: 'Test payment via SDK'
        }
      ]
      // SDK automatically handles secure signing
    });
    console.log('Payment sent:', payment.data);

    // 2. Execute team invites
    console.log('\n📧 Sending team invites...');
    const invites = await client.invites.send({
      team_nanoid: 'your_team_nanoid',
      invites: [
        {
          email: 'team@example.com',
          role: 'employee'
        }
      ]
    });
    console.log('Invites sent:', invites.data);

    // 3. Execute manager invite with automatic signing
    console.log('\n👨‍💼 Sending manager invite...');
    const managerInvite = await client.invites.sendManagerInvite({
      team_nanoid: 'your_team_nanoid',
      invites: [
        {
          email: 'manager@example.com',
          role: 'finance'
        }
      ]
      // SDK automatically handles secure signing
    });
    console.log('Manager invite sent:', managerInvite.data);

    // 4. Execute withdrawal
    console.log('\n💸 Processing withdrawal...');
    const withdrawal = await client.withdraw.sendWithdraw(
      { account_nanoid: 'your_account_nanoid' },
      {
        amount: '50.00',
        currency: 'USD',
        destination: 'bank_account'
      }
      // SDK automatically handles secure signing
    );
    console.log('Withdrawal processed:', withdrawal.data);

  } catch (error) {
    console.error('Error in advanced examples:', error.message);
  }
}

advancedExamples();

Step 5: SDK Configuration

The SDK automatically uses production environment by default, but you can specify staging for testing:

// Production (default)
const prodClient = new RiseApiClient({
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

// Staging (for testing)
const stagingClient = new RiseApiClient({
  environment: 'stg',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

// With JWT token (if you have one)
const jwtClient = new RiseApiClient({
  jwtToken: process.env.JWT_TOKEN
});

// Staging with JWT token
const stagingJwtClient = new RiseApiClient({
  environment: 'stg',
  jwtToken: process.env.JWT_TOKEN
});

Step 6: Error Handling

The SDK provides comprehensive error handling:

// error-handling.js
const { RiseApiClient } = require('@riseworks/sdk');

const client = new RiseApiClient({
  environment: process.env.RISE_ENVIRONMENT || 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

async function handleErrors() {
  try {
    // SDK automatically handles authentication errors
    const user = await client.me.get();
    console.log('User:', user.data);

  } catch (error) {
    if (error.message.includes('401')) {
      console.error('Authentication failed - verify your Rise ID and private key');
    } else if (error.message.includes('403')) {
      console.error('Permission denied - verify your role permissions');
    } else if (error.message.includes('404')) {
      console.error('Resource not found - verify the nanoid');
    } else {
      console.error('API Error:', error.message);
    }
  }
}

handleErrors();

Next Steps

Now that you have basic SDK integration configured, explore these features:

SDK Setup

Install and configure the Rise SDK

Core Concepts

Learn about RiseID, teams, roles, and entity management

API Reference

Complete API documentation with all endpoints

Webhooks

Set up webhook endpoints for real-time notifications

Payment Processing

Learn how to process payments securely

Authentication Guide

Learn about different authentication methods

Team Management

Create teams and manage members with role-based access

Error Handling

Comprehensive error handling and debugging guide

Production Ready? The SDK automatically uses production environment by default. For testing, use environment: 'stg' to connect to staging. Implement comprehensive error handling before going live. The SDK automatically handles authentication and secure signing for you.

Introduction

Authentication

SDK

Fast Setup

Secure by Default

Global Reach

Crypto Ready

​Prerequisites

​Step 1: Configure Your Environment

​Step 2: Initialize the Rise SDK

​Step 3: Execute Your Integration

​Step 4: Advanced SDK Usage

​Step 5: SDK Configuration

​Step 6: Error Handling

​Next Steps

SDK Setup

Core Concepts

API Reference

Webhooks

Payment Processing

Authentication Guide

Team Management

Error Handling

Prerequisites

Step 1: Configure Your Environment

Step 2: Initialize the Rise SDK

Step 3: Execute Your Integration

Step 4: Advanced SDK Usage

Step 5: SDK Configuration

Step 6: Error Handling

Next Steps