New to StateSet? This guide will walk you through everything from account creation to your first transaction.

​
Getting Started with StateSet

Welcome to StateSet Commerce Network! This guide will help you get up and running quickly, whether you’re building an e-commerce platform, financial application, or autonomous agent system.

​
🎯 Choose Your Path

E-Commerce

Accept payments and manage orders

Finance

Invoice factoring and trade finance

Developer

API integration and automation

​
📋 Prerequisites

Before you begin, make sure you have:
  • A modern web browser
  • Basic understanding of REST APIs
  • Node.js 16+ (for SDK usage)
  • A business email address

​
🚀 5-Minute Setup

1

Create Your Account

Visit dashboard.stateset.com and sign up:
  1. Click “Get Started”
  2. Enter your business details
  3. Verify your email
  4. Complete KYC (takes ~2 minutes)
KYC is required for mainnet access. Use testnet for immediate development.
2

Get Your API Keys

Once logged in, navigate to the API section:
  1. Go to Settings → API Keys
  2. Click “Create New Key”
  3. Name your key (e.g., “Development”)
  4. Select permissions
  5. Copy your secret key immediately
Your secret key is shown only once. Store it securely!
# Add to your .env file
STATESET_API_KEY=sk_test_4eC39HqLyjWDarjtT1zdp7dc
STATESET_WEBHOOK_SECRET=whsec_1234567890abcdef
3

Install the SDK

Choose your preferred language and install the SDK:
npm install @stateset/sdk
4

Make Your First API Call

Test your setup with a simple balance check:
import { StateSet } from '@stateset/sdk';

const stateset = new StateSet({
  apiKey: process.env.STATESET_API_KEY
});

async function checkBalance() {
  const balance = await stateset.account.balance();
  console.log('Your balance:', balance);
}

checkBalance();

​
💸 E-Commerce Quickstart

Build a complete payment flow in minutes:

​
1. Create a Product Catalog

// Create your first product
const product = await stateset.products.create({
  name: 'Premium Widget',
  price: 99.99,
  currency: 'ssusd',
  inventory: 100,
  description: 'Our best-selling widget',
  images: ['https://example.com/widget.jpg']
});

​
2. Accept Payments

// Create a checkout session
const checkout = await stateset.checkout.create({
  items: [{
    product_id: product.id,
    quantity: 2
  }],
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  customer_email: 'customer@example.com'
});

// Redirect customer to checkout
window.location.href = checkout.url;

​
3. Handle Order Fulfillment

// Listen for successful payments
stateset.webhooks.on('checkout.completed', async (event) => {
  const order = event.data;
  
  // Create shipping label
  const shipping = await stateset.shipping.create({
    order_id: order.id,
    carrier: 'fedex',
    service: 'ground',
    address: order.shipping_address
  });
  
  // Update order status
  await stateset.orders.update(order.id, {
    status: 'shipped',
    tracking_number: shipping.tracking_number
  });
});

​
Complete E-Commerce Example

// pages/api/create-checkout.js
import { StateSet } from '@stateset/sdk';

const stateset = new StateSet({
  apiKey: process.env.STATESET_API_KEY
});

export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { items } = req.body;
    
    try {
      const checkout = await stateset.checkout.create({
        items,
        success_url: `${req.headers.origin}/success`,
        cancel_url: `${req.headers.origin}/cart`
      });
      
      res.status(200).json({ url: checkout.url });
    } catch (error) {
      res.status(400).json({ error: error.message });
    }
  }
}

​
💰 Finance Quickstart

Set up invoice factoring for instant liquidity:

​
1. Connect Your Accounting System

// Connect QuickBooks, Xero, or upload invoices
const connection = await stateset.integrations.create({
  provider: 'quickbooks',
  credentials: {
    client_id: process.env.QB_CLIENT_ID,
    client_secret: process.env.QB_CLIENT_SECRET
  }
});

// Sync invoices automatically
const invoices = await stateset.invoices.sync({
  integration_id: connection.id,
  sync_unpaid: true
});

​
2. Factor an Invoice

// Get factoring options
const options = await stateset.finance.getFactoringOptions({
  invoice_id: 'inv_123',
  amount: '50000.00'
});

// Choose best option and factor
const factoring = await stateset.finance.factorInvoice({
  invoice_id: 'inv_123',
  option_id: options[0].id, // Best rate
  advance_percentage: 0.95  // 95% advance
});

console.log(`Received ${factoring.advance_amount} instantly!`);

​
🤖 Developer Quickstart

Build powerful integrations with StateSet:

​
WebSocket Subscriptions

// Real-time event streaming
const ws = stateset.subscriptions.connect();

// Subscribe to all order events
ws.subscribe('orders.*', (event) => {
  console.log('Order event:', event.type, event.data);
});

// Subscribe to specific payment events
ws.subscribe('payments.succeeded', async (event) => {
  await processSuccessfulPayment(event.data);
});

​
Batch Operations

// Batch create orders
const orders = await stateset.orders.batchCreate([
  { customer: 'cust_123', items: [...], total: 100.00 },
  { customer: 'cust_456', items: [...], total: 200.00 },
  { customer: 'cust_789', items: [...], total: 300.00 }
]);

// Batch transfer stablecoins
const transfers = await stateset.stablecoin.batchTransfer({
  transfers: [
    { to: 'address1', amount: '100.00', memo: 'Refund' },
    { to: 'address2', amount: '200.00', memo: 'Payment' },
    { to: 'address3', amount: '300.00', memo: 'Salary' }
  ]
});

​
GraphQL API

# Advanced querying with GraphQL
query GetOrderAnalytics($startDate: Date!, $endDate: Date!) {
  orders(
    where: { 
      created_at: { _gte: $startDate, _lte: $endDate },
      status: "completed"
    }
  ) {
    aggregate {
      count
      sum {
        total
      }
      avg {
        total
      }
    }
    nodes {
      id
      customer {
        email
        total_spent
      }
      items {
        product {
          name
          category
        }
        quantity
        subtotal
      }
    }
  }
}

​
🧪 Testing Your Integration

​
Use Test Mode

All API keys have test mode equivalents: 
// Test mode - no real money moves
const testClient = new StateSet({
  apiKey: 'sk_test_...' // Test key
});

// Create test payments
const payment = await testClient.payments.create({
  amount: 100.00,
  currency: 'ssusd',
  // Use test card numbers
  source: 'card_test_success'
});

​
Test Card Numbers

Card NumberScenario
4242 4242 4242 4242Success
4000 0000 0000 0002Decline
4000 0000 0000 9995Insufficient funds

​
Webhook Testing

// Use ngrok for local testing
// 1. Install ngrok: brew install ngrok
// 2. Start tunnel: ngrok http 3000
// 3. Use ngrok URL for webhooks

const webhook = await stateset.webhooks.create({
  url: 'https://abc123.ngrok.io/webhooks',
  events: ['*'], // All events
  description: 'Local development'
});

​
🚢 Going to Production

​
Pre-launch Checklist

  • Use environment variables for API keys
  • Implement webhook signature verification
  • Enable HTTPS on all endpoints
  • Set up error monitoring (Sentry, etc.)
  • Implement rate limiting
  • Add request/response logging

​
Switch to Production

// Update your configuration
const stateset = new StateSet({
  apiKey: process.env.STATESET_LIVE_KEY, // Live key
  network: 'mainnet',
  options: {
    timeout: 30000,
    retries: 3
  }
});

// Verify production access
const account = await stateset.account.retrieve();
console.log('Production account:', account.id);
console.log('Live mode:', account.live_mode); // Should be true

​
🆘 Getting Help

Documentation

Comprehensive guides and references

API Status

Check system status and uptime

Discord Community

Chat with developers and get help

Support

Contact our support team

​
🎉 Next Steps

Now that you’re set up, explore these resources:
Ready to build? You now have everything needed to start building on StateSet. If you have questions, our community is here to help!

Join our Discord

Connect with thousands of developers building the future of commerce