Token Settlement

Understand how SMART token settlement works between users, providers, and the platform during the session lifecycle.

Settlement Overview

SMART tokens flow through an escrow-based settlement process that protects both users and providers:

User purchases tokens
    |
    v
User launches session → tokens escrowed
    |
    v
Session runs → tokens held in escrow
    |
    v
Session terminates → tokens settled to provider
    |
    v
Provider accumulates balance → payout via Stripe Connect

Escrow Mechanics

When a user launches a session, the required token amount is moved from their balance into escrow:

// This happens automatically when a session is created
// The SDK surfaces escrow status in session events

gw.sessions.on('session.created', (event) => {
  console.log(event.escrow.amount);    // tokens held
  console.log(event.escrow.status);    // 'held'
  console.log(event.escrow.expiresAt); // escrow timeout
});

gw.sessions.on('session.terminated', (event) => {
  console.log(event.settlement.providerAmount); // tokens released to provider
  console.log(event.settlement.refundAmount);    // tokens returned to user (if any)
  console.log(event.settlement.platformFee);     // platform fee deducted
});

Escrow States

State	Description
held	Tokens locked in escrow, session active
settled	Session completed, tokens distributed
refunded	Session failed or cancelled, tokens returned to user
expired	Escrow timeout reached without session completion
disputed	User filed a dispute, tokens frozen pending resolution

Provider Share Calculation

The provider share is calculated at settlement time using the following formula:

provider_share = gross_session_fee * provider_rate

Where:
  gross_session_fee = base_fee + extension_fees + in_session_purchases
  provider_rate = negotiated rate (default 0.70)

Example

For a session with:

• Base fee: 100 SMART tokens
• One extension: 50 SMART tokens
• No in-session purchases

gross_session_fee = 100 + 50 + 0 = 150 tokens
platform_fee = 150 * 0.30 = 45 tokens
provider_share = 150 * 0.70 = 105 tokens

Reconciliation

Providers can reconcile their token balance against individual session settlements:

const reconciliation = await gw.provider.settlement.reconcile({
  period: '30d',
});
// reconciliation.sessions_settled: number
// reconciliation.total_gross: number
// reconciliation.total_platform_fee: number
// reconciliation.total_provider_share: number
// reconciliation.balance_matches: boolean
// reconciliation.discrepancies: Array<{ sessionId: string; expected: number; actual: number }>

Reconciliation Schedule

The platform runs automated reconciliation daily at 00:00 UTC. Any discrepancies are flagged and resolved within 24 hours. Providers receive email notifications for discrepancies exceeding 10 tokens.

Settlement Timing

Event	Settlement Timing
Session natural termination	Immediate
User-initiated termination	Immediate
Session extension	Immediate (extension fee only)
In-session purchase	Immediate
Error termination	Within 5 minutes (may include partial refund)
Escrow timeout	Within 15 minutes
Dispute filed	Frozen until resolution (up to 14 days)

Partial Settlements

If a session terminates early due to an error on the provider's side, the platform may issue a partial settlement:

gw.sessions.on('session.terminated', (event) => {
  if (event.settlement.type === 'partial') {
    console.log(event.settlement.percentageUsed); // e.g., 0.45 (45% of session time used)
    console.log(event.settlement.providerAmount); // prorated provider share
    console.log(event.settlement.refundAmount);    // prorated refund to user
  }
});

Partial settlement calculation:

time_used_ratio = actual_duration / purchased_duration
provider_amount = gross_fee * time_used_ratio * provider_rate
user_refund = gross_fee * (1 - time_used_ratio)

Viewing Settlement History

const settlements = await gw.provider.settlement.list({
  period: '7d',
  status: 'completed',
  limit: 50,
});
// settlements.items: Array<{
//   sessionId: string;
//   grossAmount: number;
//   platformFee: number;
//   providerShare: number;
//   settledAt: string;
//   type: 'full' | 'partial' | 'refunded';
// }>

Token Supply and Burn

SMART tokens operate on a fixed-supply model. Tokens used for platform fees are redistributed through the ecosystem (not burned). This ensures a stable token economy for providers planning long-term revenue projections.

For more details on the SMART token economic model, see the General Wisdom Whitepaper.