Quickstart

Get started with Rise B2B API in minutes

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

⚡ Fast Setup

Get authenticated and make 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 you begin, make sure you have:

• A Rise account with a RiseID (get one at app.rise.works)
• A Web3 wallet (MetaMask, WalletConnect, etc.)
• Node.js installed (version 16 or higher)
• Basic knowledge of JavaScript/TypeScript

Step 1: Set Up Your Environment

First, create a new project and install the required dependencies:

mkdir rise-b2b-integration
cd rise-b2b-integration
npm init -y
npm install ethers axios dotenv

Create a .env file for your configuration:

# Rise API Configuration
RISE_API_URL=https://b2b-api.riseworks.io
RISE_CHAIN_ID=42161  # Arbitrum mainnet

# Your Rise credentials
RISE_ID=rise_your_rise_id_here
WALLET_ADDRESS=0xYourWalletAddressHere
WALLET_PRIVATE_KEY=your_wallet_private_key_here

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

Step 2: Authenticate with SIWE

Create an authentication script:

// auth.js
require('dotenv').config();
const { ethers } = require('ethers');
const axios = require('axios');

class RiseAuth {
  constructor() {
    this.baseUrl = process.env.RISE_API_URL;
  }

  async authenticate(walletAddress, riseId, walletPrivateKey) {
    try {
      // Step 1: Get SIWE message
      console.log('🔐 Getting SIWE message...');
      const siweResponse = await axios.get(
        `${this.baseUrl}/v2/auth/siwe?wallet=${walletAddress}&riseid=${riseId}`
      );
      
      const { siwe } = siweResponse.data.data;
      console.log('✅ SIWE message received');

      // Step 2: Sign the message using private key
      console.log('✍️ Signing message...');
      const wallet = new ethers.Wallet(walletPrivateKey);
      const signature = await wallet.signMessage(siwe);

      // Extract nonce from the message
      const nonceMatch = siwe.match(/Nonce: (.+)/);
      const nonce = nonceMatch ? nonceMatch[1] : '';

      // Step 3: Verify signature and get JWT
      console.log('🔍 Verifying signature...');
      const verifyResponse = await axios.post(`${this.baseUrl}/v2/auth/verify`, {
        message: siwe,
        sig: signature,
        nonce: nonce
      });

      const { jwt } = verifyResponse.data.data;
      console.log('✅ Authentication successful!');
      
      return jwt;
    } catch (error) {
      console.error('❌ Authentication failed:', error.response?.data || error.message);
      throw error;
    }
  }
}

module.exports = RiseAuth;

Step 3: Make Your First API Call

Create a simple script to test the API:

// test-api.js
require('dotenv').config();
const axios = require('axios');

class RiseAPI {
  constructor(jwt) {
    this.baseUrl = process.env.RISE_API_URL;
    this.headers = {
      'Authorization': `Bearer ${jwt}`,
      'Content-Type': 'application/json'
    };
  } 

  async getUserTeams() {
    try {
      console.log('👥 Fetching user teams...');
      const response = await axios.get(
        `${this.baseUrl}/v2/user/teams`,
        { headers: this.headers }
      );
      
      console.log('✅ Teams:', response.data.data.teams);
      return response.data.data.teams;
    } catch (error) {
      console.error('❌ Failed to fetch teams:', error.response?.data || error.message);
      throw error;
    }
  }

  async getEntityBalance(nanoid) {
    try {
      console.log(`💰 Fetching balance for ${nanoid}...`);
      const response = await axios.get(
        `${this.baseUrl}/v2/balance?nanoid=${nanoid}`,
        { headers: this.headers }
      );
      
      console.log('✅ Balance:', response.data.data);
      return response.data.data;
    } catch (error) {
      console.error('❌ Failed to fetch balance:', error.response?.data || error.message);
      throw error;
    }
  }
}

module.exports = RiseAPI;

Step 4: Run Your Integration

Create a main script to test everything:

// main.js
const RiseAuth = require('./auth');
const RiseAPI = require('./test-api');

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

    // Authenticate
    const auth = new RiseAuth();
    const jwt = await auth.authenticate(
      process.env.WALLET_ADDRESS,
      process.env.RISE_ID,
      process.env.WALLET_PRIVATE_KEY
    );

    // Test API calls
    console.log('JWT Token:', jwt);
    const api = new RiseAPI(jwt);
    
    // Get user teams
    await api.getUserTeams();
    
    // Get balance (replace with actual nanoid)
    await api.getEntityBalance('your_entity_nanoid_here');

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

main();

Run your integration:

node main.js

Step 5: Next Steps

Now that you have basic authentication working, explore these features:

Payment Processing

Learn how to process payments with EIP-712 signing

Team Management

Create teams and manage members with role-based access

Web3 Integration

Understand typed data signing and blockchain operations

Error Handling

Handle errors gracefully in your integration

Platform Capabilities

Global Reach

Support for 190+ countries with local compliance

Multi-Currency

90+ local currencies and 100+ cryptocurrencies

Blockchain Security

All operations secured on Arbitrum blockchain

Real-Time Processing

Instant payment processing and balance updates

Role-Based Access

Granular permissions for team management

Developer Friendly

Comprehensive API with detailed documentation

Environment Configuration

// Development
const DEV_CONFIG = {
  baseUrl: 'https://b2b-api.dev-riseworks.io'
};

// Staging
const STAGING_CONFIG = {
  baseUrl: 'https://b2b-api.staging-riseworks.io'
};

// Production
const PROD_CONFIG = {
  baseUrl: 'https://b2b-api.riseworks.io'
};

Common Issues

Authentication Errors

Error	Solution
Wallet address is required	Ensure WALLET_ADDRESS is set in your .env file
riseid is required	Make sure RISE_ID is set and valid
Invalid signature	Verify you’re using the correct wallet and signing the exact message
SIWE error: Invalid signature	Check that the nonce matches and the message hasn’t expired

API Errors

Error	Solution
401 Unauthorized	Your JWT token has expired - re-authenticate
403 Forbidden	You don’t have permission for this operation - check your role
404 Not Found	The resource doesn’t exist - verify the nanoid

Support

Need help? Here are some resources:

Documentation

Complete authentication guide

API Reference

Full API specification

Support Email

Get help from our team

Status Page

Check API status

Production Ready? Make sure to use the production API URL (https://b2b-api.riseworks.io) and implement proper error handling before going live.