@aura-payments/sdk

TypeScript SDK for the Aura Payments Platform API. Build payment flows with multi-party escrows, Circle wallets, and real-time webhooks.

Installation

npm install @aura-payments/sdk
# or
yarn add @aura-payments/sdk
# or
pnpm add @aura-payments/sdk

Quick Start

import { AuraClient } from '@aura-payments/sdk'

const client = new AuraClient({
  apiKey: process.env.AURA_API_KEY!,
})

// Create a multi-party escrow
const escrow = await client.escrows.create({
  orderId: 'order-123',
  amountUsdc: '100.00',
  splits: {
    vendorEntityId: 'vendor-1',
    sellerEntityId: 'seller-1',
    platformEntityId: 'platform-1',
    vendorPercentage: 70,
    sellerPercentage: 20,
    platformPercentage: 10,
  },
  adminSafeAddress: '0x...',
})

console.log(`Escrow created: ${escrow.escrowId}`)
console.log(`Vault address: ${escrow.vaultAddress}`)

Features

• Type-Safe - Full TypeScript support with comprehensive type definitions
• Dual Module Support - Works with ESM and CommonJS
• Automatic Retries - Exponential backoff with jitter for failed requests
• Idempotency - Automatic idempotency key generation for safe retries
• Error Handling - Typed error classes with type guards
• Webhook Validation - HMAC-SHA256 signature verification

Configuration

import { AuraClient } from '@aura-payments/sdk'

const client = new AuraClient({
  // Required: Your API key from the Aura dashboard
  apiKey: 'ak_live_...',

  // Optional: API base URL (default: https://api.aura-payments.com)
  baseUrl: 'https://api.aura-payments.com',

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,

  // Optional: Max retry attempts (default: 3)
  maxRetries: 3,

  // Optional: Auto-generate idempotency keys (default: true)
  autoIdempotency: true,
})

API Reference

Escrows

Escrows enable secure multi-party payments with configurable splits and release conditions.

Create Escrow

const escrow = await client.escrows.create({
  orderId: 'order-123',
  amountUsdc: '100.00',
  splits: {
    vendorEntityId: 'vendor-uuid',
    sellerEntityId: 'seller-uuid',
    platformEntityId: 'platform-uuid',
    vendorPercentage: 70,
    sellerPercentage: 20,
    platformPercentage: 10,
  },
  adminSafeAddress: '0x...',
  unlock: {
    type: 'timeout', // 'oracle' | 'timeout' | 'hybrid' | 'manual'
    days: 14,
  },
  items: [
    {
      orderItemId: 'item-1',
      description: 'Premium Widget',
      amountUsdc: '100.00',
    },
  ],
})

Get Escrow

const escrow = await client.escrows.get('escrow-id')

List Escrows

const { data, pagination } = await client.escrows.list({
  page: 1,
  limit: 20,
  status: 'funded', // 'pending' | 'funded' | 'locked' | 'released' | 'refunded' | 'disputed'
  orderId: 'order-123',
})

Fund Escrow

const funded = await client.escrows.fund({
  escrowId: 'escrow-id',
  fromEntityId: 'buyer-entity-id',
  amountUsdc: '100.00',
})

Release Escrow

// Full release
const released = await client.escrows.release({
  escrowId: 'escrow-id',
})

// Partial release
const partialRelease = await client.escrows.release({
  escrowId: 'escrow-id',
  partial: {
    itemIds: ['item-1', 'item-2'],
  },
})

// With multisig signature
const signedRelease = await client.escrows.release({
  escrowId: 'escrow-id',
  signature: {
    digest: '0x...',
    signature: '0x...',
  },
})

Refund Escrow

const refunded = await client.escrows.refund({
  escrowId: 'escrow-id',
  reason: 'vendor_reject', // 'vendor_reject' | 'sla_breach' | 'manual' | 'dispute_resolved'
  toEntityId: 'buyer-entity-id',
  amountUsdc: '50.00', // Optional: partial refund
})

Disputes

// Open a dispute
const dispute = await client.escrows.createDispute({
  escrowId: 'escrow-id',
  openedByEntityId: 'buyer-entity-id',
  reason: 'Item not as described',
  evidenceUrl: 'https://...',
})

// Get dispute details
const disputeDetails = await client.escrows.getDispute('escrow-id', 'dispute-id')

Wallets

Manage Circle Developer-Controlled Wallets for your entities.

Create Wallet

const wallet = await client.wallets.create({
  entityId: 'entity-uuid',
  chain: 'ARC', // 'ARC' | 'ARB' | 'BASE' | 'ETH' | 'MATIC' | 'SOL'
  type: 'developer_controlled', // 'developer_controlled' | 'user_controlled'
})

Get Wallet

const wallet = await client.wallets.get('wallet-id')

List Wallets

const { data, pagination } = await client.wallets.list({
  entityId: 'entity-uuid',
  chain: 'ARC',
  type: 'developer_controlled',
  page: 1,
  limit: 20,
})

Get Balance

const balance = await client.wallets.getBalance('wallet-id')
// Returns: { walletId, address, chain, balances: [{ token, amount, decimals, symbol }] }

Transfer Funds

const transfer = await client.wallets.transfer({
  fromWalletId: 'wallet-id',
  toAddress: '0x...',
  amount: '50.00',
  token: 'USDC',
})

// Check transfer status
const status = await client.wallets.getTransfer('wallet-id', transfer.id)

Webhooks

Configure webhook endpoints to receive real-time payment events.

Configure Webhook

const config = await client.webhooks.configure({
  url: 'https://your-app.com/webhooks/aura',
  events: [
    'escrow.created',
    'escrow.funded',
    'escrow.released',
    'escrow.refunded',
    'escrow.disputed',
    'wallet.created',
    'transfer.completed',
    'transfer.failed',
    'dispute.opened',
    'dispute.resolved',
  ],
})

Get Webhook Config

const config = await client.webhooks.getConfig()

Delete Webhook

await client.webhooks.delete()

Validate Webhook Signature

import { Webhooks } from '@aura-payments/sdk'

// In your webhook handler
app.post('/webhooks/aura', (req, res) => {
  const signature = req.headers['x-aura-signature'] as string
  const secret = process.env.AURA_WEBHOOK_SECRET!

  const result = Webhooks.validateSignature({
    payload: req.body,
    signature,
    secret,
  })

  if (!result.valid) {
    console.error('Invalid webhook signature:', result.error)
    return res.status(401).send('Invalid signature')
  }

  const event = result.event!

  switch (event.type) {
    case 'escrow.funded':
      console.log('Escrow funded:', event.data)
      break
    case 'escrow.released':
      console.log('Escrow released:', event.data)
      break
    case 'transfer.completed':
      console.log('Transfer completed:', event.data)
      break
  }

  res.status(200).send('OK')
})

Error Handling

The SDK provides typed error classes for different failure scenarios:

import {
  AuraError,
  AuraAPIError,
  AuraNetworkError,
  AuraTimeoutError,
  AuraValidationError,
  AuraAuthenticationError,
  AuraNotFoundError,
  AuraRateLimitError,
  isAuraError,
  isRetryableError,
} from '@aura-payments/sdk'

try {
  await client.escrows.get('invalid-id')
} catch (error) {
  if (error instanceof AuraNotFoundError) {
    console.log('Escrow not found')
  } else if (error instanceof AuraValidationError) {
    console.log('Validation failed:', error.details)
  } else if (error instanceof AuraAuthenticationError) {
    console.log('Invalid API key')
  } else if (error instanceof AuraRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`)
  } else if (error instanceof AuraNetworkError) {
    console.log('Network error:', error.cause)
  } else if (error instanceof AuraTimeoutError) {
    console.log('Request timed out')
  } else if (isAuraError(error)) {
    console.log(`API error: ${error.message} (${error.code})`)
  }

  // Check if error is retryable
  if (isRetryableError(error)) {
    // Implement retry logic
  }
}

Error Types

| Error Class | Status Code | Description | |-------------|-------------|-------------| | AuraValidationError | 400 | Invalid request parameters | | AuraAuthenticationError | 401 | Invalid or missing API key | | AuraNotFoundError | 404 | Resource not found | | AuraRateLimitError | 429 | Rate limit exceeded | | AuraTimeoutError | 408 | Request timeout | | AuraNetworkError | - | Network connectivity issue | | AuraAPIError | 5xx | Server error |

TypeScript Types

All types are exported for use in your application:

import type {
  // Client
  AuraClientConfig,

  // Escrow types
  Escrow,
  EscrowStatus,
  EscrowSplit,
  UnlockType,
  DisputeStatus,
  Dispute,
  CreateEscrowParams,
  CreateEscrowResponse,
  FundEscrowParams,
  ReleaseEscrowParams,
  RefundEscrowParams,
  CreateDisputeParams,
  ListEscrowsParams,
  ListEscrowsResponse,

  // Wallet types
  Wallet,
  WalletBalance,
  TokenBalance,
  Chain,
  WalletType,
  CreateWalletParams,
  TransferParams,
  Transfer,
  ListWalletsParams,
  ListWalletsResponse,

  // Webhook types
  WebhookEvent,
  WebhookEventType,
  WebhookConfig,
  ConfigureWebhookParams,
  WebhookValidationResult,
  ValidateWebhookSignatureOptions,

  // Shared types
  PaginationParams,
  PaginatedResponse,
} from '@aura-payments/sdk'

Utilities

The SDK exports utility functions for advanced use cases:

import {
  generateIdempotencyKey,
  retryWithBackoff,
  withTimeout,
  calculateBackoff,
} from '@aura-payments/sdk'

// Generate a unique idempotency key
const key = generateIdempotencyKey()
// Returns: "1703001234567-abc123def456"

// Retry a function with exponential backoff
const result = await retryWithBackoff(
  () => someAsyncOperation(),
  3 // max retries
)

// Add timeout to any promise
const result = await withTimeout(
  fetch('https://api.example.com'),
  5000 // timeout in ms
)

Idempotency

All state-changing operations (POST/PUT) automatically include idempotency keys to ensure safe retries. You can provide your own:

// Auto-generated idempotency key (default)
await client.escrows.create(params)

// Custom idempotency key
await client.escrows.create(params, 'my-unique-key-123')

// Disable auto-generation globally
const client = new AuraClient({
  apiKey: '...',
  autoIdempotency: false,
})

Supported Chains

| Chain | Identifier | Network | |-------|------------|---------| | Arc | ARC | Arc Testnet / Mainnet | | Arbitrum | ARB | Arbitrum Sepolia / One | | Base | BASE | Base Sepolia / Mainnet | | Ethereum | ETH | Ethereum Mainnet | | Polygon | MATIC | Polygon Mainnet | | Solana | SOL | Solana Mainnet |

Requirements

• Node.js 18+ (for native fetch support)
• TypeScript 5.x (for best type inference)

License

MIT