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

Create Your Account

Visit dashboard.stateset.com and sign up:

Click “Get Started”
Enter your business details
Verify your email
Complete KYC (takes ~2 minutes)

KYC is required for mainnet access. Use testnet for immediate development.

Get Your API Keys

Once logged in, navigate to the API section:

Go to Settings → API Keys
Click “Create New Key”
Name your key (e.g., “Development”)
Select permissions
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_your_actual_key_here
STATESET_WEBHOOK_SECRET=whsec_your_webhook_secret_here

Install the SDK

Choose your preferred language and install the SDK:

npm install @stateset/sdk

pip install stateset

go get github.com/stateset/stateset-go

Make Your First API Call

Test your setup with a simple balance check:

import { StateSet } from '@stateset/sdk';

// Replace with a structured logger (Winston, Pino, etc) in production
const logger = console;

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

async function checkBalance() {
  const balance = await stateset.account.balance();
  logger.info('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 });
    }
  }
}

from flask import Flask, request, jsonify
from stateset import StateSet
import os

app = Flask(__name__)
stateset = StateSet(api_key=os.getenv('STATESET_API_KEY'))

@app.route('/api/create-checkout', methods=['POST'])
def create_checkout():
    data = request.json
    
    try:
        checkout = stateset.checkout.create(
            items=data['items'],
            success_url=f"{request.host_url}success",
            cancel_url=f"{request.host_url}cart"
        )
        
        return jsonify({'url': checkout.url})
    except Exception as e:
        return jsonify({'error': str(e)}), 400

💰 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

// Replace with a structured logger (Winston, Pino, etc) in production
const logger = console;

// 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
});

logger.info('Invoice factored', { advanceAmount: factoring.advance_amount });

🤖 Developer Quickstart

Build powerful integrations with StateSet:

WebSocket Subscriptions

// Replace with a structured logger (Winston, Pino, etc) in production
const logger = console;

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

// Subscribe to all order events
ws.subscribe('orders.*', (event) => {
  logger.info('Order event received', { type: event.type, data: 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 Number	Scenario
`4242 4242 4242 4242`	Success
`4000 0000 0000 0002`	Decline
`4000 0000 0000 9995`	Insufficient 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

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();
// Replace with a structured logger (Winston, Pino, etc) in production
const logger = console;
logger.info('Production account', { accountId: account.id });
logger.info('Live mode', { liveMode: 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

StateSet Commerce Network API Authentication

​Getting Started with StateSet

​🎯 Choose Your Path

E-Commerce

Finance

Developer

​📋 Prerequisites

​🚀 5-Minute Setup

​💸 E-Commerce Quickstart

​1. Create a Product Catalog

​2. Accept Payments

​3. Handle Order Fulfillment

​Complete E-Commerce Example

​💰 Finance Quickstart

​1. Connect Your Accounting System

​2. Factor an Invoice

​🤖 Developer Quickstart

​WebSocket Subscriptions

​Batch Operations

​GraphQL API

​🧪 Testing Your Integration

​Use Test Mode

​Test Card Numbers

​Webhook Testing

​🚢 Going to Production

​Pre-launch Checklist

​Switch to Production

​🆘 Getting Help

Documentation

API Status

Discord Community

Support

​🎉 Next Steps

Join our Discord

Getting Started with StateSet

🎯 Choose Your Path

📋 Prerequisites

🚀 5-Minute Setup

💸 E-Commerce Quickstart

1. Create a Product Catalog

2. Accept Payments

3. Handle Order Fulfillment

Complete E-Commerce Example

💰 Finance Quickstart

1. Connect Your Accounting System

2. Factor an Invoice

🤖 Developer Quickstart

WebSocket Subscriptions

Batch Operations

GraphQL API

🧪 Testing Your Integration

Use Test Mode

Test Card Numbers

Webhook Testing

🚢 Going to Production

Pre-launch Checklist

Switch to Production

🆘 Getting Help

🎉 Next Steps