nuorbit-sdk-server-ts

TypeScript SDK for server-side NuOrbit payment integration.

This SDK handles API authentication securely on the backend - never expose credentials to the frontend!

Installation

npm install nuorbit-sdk-server-ts
# or
pnpm add nuorbit-sdk-server-ts
# or
yarn add nuorbit-sdk-server-ts

Quick Start

import { NuOrbitClient } from 'nuorbit-sdk-server-ts'

const client = new NuOrbitClient({
  baseUrl: 'https://api.nuorbit.io',
  apiKey: process.env.NUORBIT_API_KEY!,
  apiSecret: process.env.NUORBIT_API_SECRET!,
})

// Create an order
const order = await client.createOrder({
  dappOrderId: 'my-order-123',
  chainId: 97,
  tokenSymbol: 'USDC',
  tokenContract: '0x...',
  fromAddress: userWalletAddress,
  amountWei: '1000000', // 1 USDC (6 decimals)
})

// Return order to frontend for payment
res.json(order)

Features

• ✅ HMAC-SHA256 request signing for secure API authentication
• ✅ Complete order lifecycle management (create, query, cancel)
• ✅ EIP-3009 gasless payment support
• ✅ Merchant info retrieval
• ✅ Order confirmation polling with auto-retry
• ✅ Full TypeScript type definitions
• ✅ x402 protocol support

API Reference

NuOrbitClient

Constructor

new NuOrbitClient(config: NuOrbitConfig)

Parameters:

• config.baseUrl - API base URL (e.g., https://api.nuorbit.io)
• config.apiKey - Your merchant API key
• config.apiSecret - Your merchant API secret (keep secure!)

Methods

createOrder()

Create a new payment order.

async createOrder(params: CreateOrderParams): Promise<Order>

Example:

const order = await client.createOrder({
  dappOrderId: 'order-123',
  chainId: 97,
  fromChainId: 97, // Optional, for cross-chain payments
  tokenSymbol: 'USDC',
  tokenContract: '0x...',
  fromAddress: '0x...',
  amountWei: '1000000',
  flow: 'ERC20_3009', // Optional: ERC20_DIRECT, ERC20_3009, ERC20_APPROVE_XFER
  callbackCalldata: '0x...', // Optional, for DELEGATE merchants
})

getOrderStatus()

Get order status (for polling).

async getOrderStatus(orderId: string): Promise<OrderProof>

submitEIP3009Signature()

Submit user's EIP-3009 signature for gasless transfer.

async submitEIP3009Signature(
  orderId: string,
  params: EIP3009SignatureParams
): Promise<void>

submitCalldataSignature()

Submit user's EIP-712 calldata signature (for DELEGATE merchants).

async submitCalldataSignature(
  orderId: string,
  signature: string
): Promise<void>

getMerchant()

Get merchant information (public API, no auth required).

async getMerchant(merchantId: string): Promise<MerchantInfo>

waitForConfirmation()

Poll for order confirmation with automatic retry.

async waitForConfirmation(
  orderId: string,
  options?: {
    timeout?: number      // Default: 5 minutes
    interval?: number     // Default: 3 seconds
    onStatusChange?: (status: string) => void
  }
): Promise<OrderProof>

Example:

const result = await client.waitForConfirmation(orderId, {
  timeout: 2 * 60 * 1000, // 2 minutes
  onStatusChange: (status) => console.log('Status:', status),
})

if (result.status === 'PAYMENT_CONFIRMED') {
  console.log('Payment confirmed!', result.txHash)
}

Authentication

The SDK uses HMAC-SHA256 signature authentication:

1. Sorts all parameters alphabetically
2. Concatenates as key1=value1&key2=value2
3. Signs with HMAC-SHA256 using your API secret
4. Sends signature in X-Sign header along with X-API-Key and X-Timestamp

Never expose your API secret to the frontend!

Order Status Flow

CHECKOUT_VERIFIED → PAYMENT_CONFIRMED → INVOICED
                 ↘ FAILED
                 ↘ EXPIRED
                 ↘ CANCELLED

Error Handling

import { NuOrbitError } from 'nuorbit-sdk-server-ts'

try {
  const order = await client.createOrder({ ... })
} catch (error) {
  if (error instanceof NuOrbitError) {
    console.error('API Error:', error.message)
    console.error('Status:', error.status)
    console.error('Code:', error.code)
  }
}

TypeScript Support

Full TypeScript definitions included:

import type {
  Order,
  OrderProof,
  OrderStatus,
  PaymentFlow,
  MerchantInfo,
  CreateOrderParams,
  EIP3009SignRequest,
} from 'nuorbit-sdk-server-ts'

x402 Protocol

This SDK supports the x402 payment protocol. Use createOrderRaw() for full x402 response access:

const x402Response = await client.createOrderRaw({ ... })
console.log(x402Response.accepts) // Payment options
console.log(x402Response.extensions?.nuorbit) // NuOrbit extensions

Security Best Practices

1. Store credentials securely: Use environment variables, not hardcoded values
2. Keep SDK updated: Check for security updates regularly
3. Validate webhook signatures: Use HMAC verification for webhooks
4. Use HTTPS: Always connect to API via HTTPS
5. Rate limiting: Implement rate limiting on your endpoints

Example: Express.js Server

import express from 'express'
import { NuOrbitClient } from 'nuorbit-sdk-server-ts'

const app = express()
app.use(express.json())

const client = new NuOrbitClient({
  baseUrl: process.env.NUORBIT_API_URL!,
  apiKey: process.env.NUORBIT_API_KEY!,
  apiSecret: process.env.NUORBIT_API_SECRET!,
})

app.post('/api/orders', async (req, res) => {
  try {
    const order = await client.createOrder({
      dappOrderId: `order-${Date.now()}`,
      chainId: req.body.chainId,
      tokenSymbol: req.body.tokenSymbol,
      tokenContract: req.body.tokenContract,
      fromAddress: req.body.fromAddress,
      amountWei: req.body.amountWei,
    })
    res.json(order)
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})

app.listen(3000)

Links

• Documentation
• GitHub
• NPM

License

MIT