Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)
    1. Docs
    2. /API
    3. /Wallet API
    Updated Jul 21, 20266 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    1. Docs
    2. /API
    3. /Wallet API
    Updated Jul 21, 20266 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    1. Docs
    2. /API
    3. /Wallet API
    Updated Jul 21, 20266 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    Wallet API

    Filter with Founder / Developer in the docs sidebar. Prefer Server Actions for UI. HTTP routes remain for MCP, webhooks, and non-React clients. Desk oracle rate lives in platform_settings / web3 via ring-token-oracle.ts — separate from fiat credit accounting.

    Ring Platform wallet operations use two layers:

    1. Server Actions (preferred for React) — app/_actions/wallet.ts — type-safe, revalidatePath, works with useActionState.
    2. API Routes — app/api/wallet/**/route.ts — session-cookie HTTP for external integrations and MCP.

    Browser calls use Auth.js session cookies on the same origin — see API reference. UI entry: /wallet (protected).

    What members experience

    Wallet feature

    Dashboard, fiat credit points, Token Desk conversion, gasless native sends.

    Store & credits

    Store checkout debits credit points via PaymentConductor internal_credit (same fiat rate SSOT).

    Authentication

    Social sign-in provisions custodial wallets automatically.

    Web3 desk (admin)

    Superadmin sets native-token oracle rate and gas reserve — not member-facing.

    Two rates — do not mix them

    RateConfigUsed for
    Fiat credit accountingring-config.json → credit.unitToDefaultCurrency (usually 1)Debiting/crediting points vs store defaultCurrency
    Token Desk oracleplatform_settings.web3.oracle.ringPerUsdConverting points ↔ native token on the desk

    Keep credit.unitToDefaultCurrency at 1 unless you intentionally scale points vs fiat. Changing the desk oracle (ringPerUsd) never changes store or ad-hoc credit spend math.

    Typical member flows

    • First login — ensureUserWallets / WalletConductor.ensureNativeWallet provisions custodial address (Solana or EVM per clone).
    • Check balance — listUserWallets + getCreditBalance.
    • Send native tokens — transferNativeTokens (treasury-sponsored gas on Solana).
    • Top up credits (card / PayPal) — initiateCreditTopupPayment → WalletConductor.initiateTopUp → PaymentConductor wallet_topup → UI followCheckoutResult(redirect) → webhook credits ledger. Card uses env processor; PayPal tab sends processor=paypal.
    • Top up credits (chain proof) — topUpCredits / verifyTopUpTransaction.
    • Pay with credits (ad-hoc) — spendCredits Server Action or POST /api/wallet/credit/spend.
    • Pay in store — checkout rail internal_credit (PaymentConductor), not a raw UI call to /credit/spend.

    Custodial model: Ring signs transfers server-side for social-auth wallets. External wallets (MetaMask, Coinbase Wallet, WalletConnect via the Wagmi v3 connector picker) connect client-side — they do not use custodial server actions.

    Server actions (preferred)

    All server actions live in app/_actions/wallet.ts. Pattern: auth → service / WalletConductor → revalidatePath.

    Inventory (high-signal)

    ActionRole
    ensureUserWallets / listUserWallets / getWalletBalanceProvision + list custodial wallets
    getCreditBalance / getCreditHistory / getSpendSummaryFiat ledger reads
    topUpCredits / spendCredits / transferCreditsFiat ledger mutations (spendCredits → WalletConductor.spendCredits)
    initiateCreditTopupPaymentThin adapter → WalletConductor.initiateTopUp → PaymentConductor wallet_topup; returns { redirect, paymentUrl?, paymentFields? } — client must call followCheckoutResult
    transferNativeTokensGasless native-token send

    Related documentation

    Related documentation

    Tunnel Protocol

    Depends-on: `credit:balance` and `wallet:list` Tunnel channels that refresh this API's UI consumers.

    WalletConductor architecture

    Deep-dive: facade methods that publish wallet-list updates after transferNative / ensure.

    Wallet & Credit System

    Next-step: member-facing wallet dashboard and credit vs native rails.

    API Reference

    See-also: session auth model and domain API map.

    Wallet API

    Filter with Founder / Developer in the docs sidebar. Prefer Server Actions for UI. HTTP routes remain for MCP, webhooks, and non-React clients. Desk oracle rate lives in platform_settings / web3 via ring-token-oracle.ts — separate from fiat credit accounting.

    Ring Platform wallet operations use two layers:

    1. Server Actions (preferred for React) — app/_actions/wallet.ts — type-safe, revalidatePath, works with useActionState.
    2. API Routes — app/api/wallet/**/route.ts — session-cookie HTTP for external integrations and MCP.

    Browser calls use Auth.js session cookies on the same origin — see API reference. UI entry: /wallet (protected).

    What members experience

    Wallet feature

    Dashboard, fiat credit points, Token Desk conversion, gasless native sends.

    Store & credits

    Store checkout debits credit points via PaymentConductor internal_credit (same fiat rate SSOT).

    Authentication

    Social sign-in provisions custodial wallets automatically.

    Web3 desk (admin)

    Superadmin sets native-token oracle rate and gas reserve — not member-facing.

    Two rates — do not mix them

    RateConfigUsed for
    Fiat credit accountingring-config.json → credit.unitToDefaultCurrency (usually 1)Debiting/crediting points vs store defaultCurrency
    Token Desk oracleplatform_settings.web3.oracle.ringPerUsdConverting points ↔ native token on the desk

    Keep credit.unitToDefaultCurrency at 1 unless you intentionally scale points vs fiat. Changing the desk oracle (ringPerUsd) never changes store or ad-hoc credit spend math.

    Typical member flows

    • First login — ensureUserWallets / WalletConductor.ensureNativeWallet provisions custodial address (Solana or EVM per clone).
    • Check balance — listUserWallets + getCreditBalance.
    • Send native tokens — transferNativeTokens (treasury-sponsored gas on Solana).
    • Top up credits (card / PayPal) — initiateCreditTopupPayment → WalletConductor.initiateTopUp → PaymentConductor wallet_topup → UI followCheckoutResult(redirect) → webhook credits ledger. Card uses env processor; PayPal tab sends processor=paypal.
    • Top up credits (chain proof) — topUpCredits / verifyTopUpTransaction.
    • Pay with credits (ad-hoc) — spendCredits Server Action or POST /api/wallet/credit/spend.
    • Pay in store — checkout rail internal_credit (PaymentConductor), not a raw UI call to /credit/spend.

    Custodial model: Ring signs transfers server-side for social-auth wallets. External wallets (MetaMask, Coinbase Wallet, WalletConnect via the Wagmi v3 connector picker) connect client-side — they do not use custodial server actions.

    Server actions (preferred)

    All server actions live in app/_actions/wallet.ts. Pattern: auth → service / WalletConductor → revalidatePath.

    Inventory (high-signal)

    ActionRole
    ensureUserWallets / listUserWallets / getWalletBalanceProvision + list custodial wallets
    getCreditBalance / getCreditHistory / getSpendSummaryFiat ledger reads
    topUpCredits / spendCredits / transferCreditsFiat ledger mutations (spendCredits → WalletConductor.spendCredits)
    initiateCreditTopupPaymentThin adapter → WalletConductor.initiateTopUp → PaymentConductor wallet_topup; returns { redirect, paymentUrl?, paymentFields? } — client must call followCheckoutResult
    transferNativeTokensGasless native-token send

    Related documentation

    Related documentation

    Tunnel Protocol

    Depends-on: `credit:balance` and `wallet:list` Tunnel channels that refresh this API's UI consumers.

    WalletConductor architecture

    Deep-dive: facade methods that publish wallet-list updates after transferNative / ensure.

    Wallet & Credit System

    Next-step: member-facing wallet dashboard and credit vs native rails.

    API Reference

    See-also: session auth model and domain API map.

    Wallet API

    Filter with Founder / Developer in the docs sidebar. Prefer Server Actions for UI. HTTP routes remain for MCP, webhooks, and non-React clients. Desk oracle rate lives in platform_settings / web3 via ring-token-oracle.ts — separate from fiat credit accounting.

    Ring Platform wallet operations use two layers:

    1. Server Actions (preferred for React) — app/_actions/wallet.ts — type-safe, revalidatePath, works with useActionState.
    2. API Routes — app/api/wallet/**/route.ts — session-cookie HTTP for external integrations and MCP.

    Browser calls use Auth.js session cookies on the same origin — see API reference. UI entry: /wallet (protected).

    What members experience

    Wallet feature

    Dashboard, fiat credit points, Token Desk conversion, gasless native sends.

    Store & credits

    Store checkout debits credit points via PaymentConductor internal_credit (same fiat rate SSOT).

    Authentication

    Social sign-in provisions custodial wallets automatically.

    Web3 desk (admin)

    Superadmin sets native-token oracle rate and gas reserve — not member-facing.

    Two rates — do not mix them

    RateConfigUsed for
    Fiat credit accountingring-config.json → credit.unitToDefaultCurrency (usually 1)Debiting/crediting points vs store defaultCurrency
    Token Desk oracleplatform_settings.web3.oracle.ringPerUsdConverting points ↔ native token on the desk

    Keep credit.unitToDefaultCurrency at 1 unless you intentionally scale points vs fiat. Changing the desk oracle (ringPerUsd) never changes store or ad-hoc credit spend math.

    Typical member flows

    • First login — ensureUserWallets / WalletConductor.ensureNativeWallet provisions custodial address (Solana or EVM per clone).
    • Check balance — listUserWallets + getCreditBalance.
    • Send native tokens — transferNativeTokens (treasury-sponsored gas on Solana).
    • Top up credits (card / PayPal) — initiateCreditTopupPayment → WalletConductor.initiateTopUp → PaymentConductor wallet_topup → UI followCheckoutResult(redirect) → webhook credits ledger. Card uses env processor; PayPal tab sends processor=paypal.
    • Top up credits (chain proof) — topUpCredits / verifyTopUpTransaction.
    • Pay with credits (ad-hoc) — spendCredits Server Action or POST /api/wallet/credit/spend.
    • Pay in store — checkout rail internal_credit (PaymentConductor), not a raw UI call to /credit/spend.

    Custodial model: Ring signs transfers server-side for social-auth wallets. External wallets (MetaMask, Coinbase Wallet, WalletConnect via the Wagmi v3 connector picker) connect client-side — they do not use custodial server actions.

    Server actions (preferred)

    All server actions live in app/_actions/wallet.ts. Pattern: auth → service / WalletConductor → revalidatePath.

    Inventory (high-signal)

    ActionRole
    ensureUserWallets / listUserWallets / getWalletBalanceProvision + list custodial wallets
    getCreditBalance / getCreditHistory / getSpendSummaryFiat ledger reads
    topUpCredits / spendCredits / transferCreditsFiat ledger mutations (spendCredits → WalletConductor.spendCredits)
    initiateCreditTopupPaymentThin adapter → WalletConductor.initiateTopUp → PaymentConductor wallet_topup; returns { redirect, paymentUrl?, paymentFields? } — client must call followCheckoutResult
    transferNativeTokensGasless native-token send

    Related documentation

    Related documentation

    Tunnel Protocol

    Depends-on: `credit:balance` and `wallet:list` Tunnel channels that refresh this API's UI consumers.

    WalletConductor architecture

    Deep-dive: facade methods that publish wallet-list updates after transferNative / ensure.

    Wallet & Credit System

    Next-step: member-facing wallet dashboard and credit vs native rails.

    API Reference

    See-also: session auth model and domain API map.

    executeDeskQuote
    Credit ↔ native desk trade
    createPinAccessTokenActionPIN-gated single-use access token

    Credit spend rate SSOT

    Fiat ledger debits must use the config multiplier — never the desk oracle.

    Fiat credit accounting rate
    FactTruth
    SSOTring-config.json → credit.unitToDefaultCurrency (usually 1)
    HelpersgetCreditUnitToDefaultCurrencyRate / getFiatCreditAccountingRate in lib/ring-config-core.ts + lib/payments/credit-currency.ts
    FallbackexchangeRates[defaultCurrency], then 1
    Ad-hoc debitWalletConductor.spendCredits (Server Action omits usdRate → conductor defaults to fiat helper)
    Store checkoutPaymentConductor internal_credit → internal-credit.processor.ts (also calls getFiatCreditAccountingRate)
    Neverplatform_settings.web3.oracle.ringPerUsd / getRingPerUsdRate for fiat usdRate
    Desk onlyring-token-oracle / pointsPerNativeToken for points ↔ RING

    Document POST /api/wallet/credit/spend only. A GET stub may return 410 in code — it is not a capability. Use getSpendSummary or GET /api/wallet/credit/history for reads.

    Action call pattern

    Server action auth gate

    HTTP routes (external / MCP)

    Wallet lifecycle

    MethodPathNotes
    GET/api/wallet/list{ wallets } via listWallets() — ?refresh=true force on-chain via refreshBalancesForUser (publishes wallet:list)
    POST/api/wallet/ensureIdempotent create-if-missing — ensureWallets publishes wallet:list when provisioning changes
    GET/api/wallet/balanceDefault wallet native-token balance

    Native-token operations

    MethodPathNotes
    GET/api/wallet/token/balance{ balance, address, chain, symbol }
    POST/api/wallet/token/transferCustodial native-token send; wallet_transactions row
    POST/api/wallet/transferExternal EVM custodial POL path when chains.enabled includes evm — not Solana native SSOT

    Activity

    MethodPathNotes
    GET/api/wallet/activityfilter=all|credit|chain, unified feed

    Credit ledger

    MethodPathNotes
    GET/api/wallet/credit/balanceBalance + spend limits — live UI via Tunnel credit:balance (publishToUserTunnel after ledger mutations)
    PUT/api/wallet/credit/balanceAdmin airdrop { user_id, amount, reason }
    POST/api/wallet/credit/topupOptional tx_hash verification
    POST/api/wallet/credit/spendDirect fiat debit via WalletConductor.spendCredits + unitToDefaultCurrency
    GET/api/wallet/credit/historyPaginated ledger

    Schemas: lib/zod/credit-schemas.ts. Service: features/wallet/services/credit-balance-service.ts.

    Solana desk

    MethodPathNotes
    GET/api/wallet/desk/quoteQuery side, amount
    POST/api/wallet/desk/execute{ idempotencyKey, quoteToken }

    SSOT file reference

    ConcernFileKey exports
    Credit CRUDfeatures/wallet/services/credit-balance-service.tsaddCredits, spendCredits, getCreditHistory
    Conductorfeatures/wallet/conductor/wallet-conductor.tsspendCredits, ensureNativeWallet
    Fiat ratelib/ring-config-core.ts / lib/payments/credit-currency.tsgetCreditUnitToDefaultCurrencyRate, getFiatCreditAccountingRate
    Store credit checkoutlib/payments/processors/internal-credit.processor.tscreateInternalCreditCheckout
    Gasless transfersfeatures/wallet/chains/native-token-transfer-service.tstransferNativeTokenForUser
    Desk tradesfeatures/wallet/chains/solana/desk-service.tsquoteDesk, executeDesk
    Native oraclefeatures/wallet/services/ring-token-oracle.tsgetRingPerUsdRate, setRingPerUsdRate
    Wallet DBlib/wallet/user-wallet-db.tsgetUserWallets, getNativeWallet
    PIN tokenslib/wallet/pin-access-token-db.tsissueAccessToken, consumeAccessToken

    Example — spend credits

    1. 1

      Prefer Server Action (React UI)

      Form fields: amount (required), description (optional — defaults to Credit spend), orderId (optional). Conductor applies getFiatCreditAccountingRate() when usdRate is omitted.

    2. 2

      Or HTTP POST (external / MCP)

      CreditSpendRequestSchema requires amount and description. Body may include optional order_id, reference_id, metadata.

    3. 3

      Store checkout (do not call spend HTTP from store UI)

      PaymentConductor rail internal_credit → internal-credit.processor.ts → creditBalanceService.spendCredits with the same fiat rate helper.

    Environment variables

    VariableRequiredUsed by
    WALLET_ENCRYPTION_KEYYesAES-256-GCM wallet secrets
    SOLANA_RPC_URLYesSolana RPC
    SOLANA_TREASURY_PRIVATE_KEYYesSponsored gas / treasury ops
    WALLET_ACCESS_TOKEN_TTL_SECONDSNo (default 900)PIN access tokens
    ORACLE_QUOTE_SECRETDeskQuote HMAC (falls back to WALLET_ENCRYPTION_KEY)
    RING_ORACLE_DEFAULT_RATENoDesk oracle fallback when DB disabled
    PLATFORM_SETTINGS_DISABLE_DBNoEnv-only oracle reads

    Desk oracle persistence (native token only)

    Desk oracle read path

    Admin write: setRingPerUsdRate or POST /api/admin/web3/settings.

    Authentication

    Prerequisite: crypto wallet provider + social login that provisions custodial wallets.

    Token Economics Setup

    See-also: desk oracle, transfer tax, first-settler discounts.

    Ethereum wallets (Wagmi v3)

    See-also: Wagmi pathNeedsWeb3 and getWalletBalance live in app/_actions/wallet.ts (dead get-wallet-balance.ts removed).

    executeDeskQuote
    Credit ↔ native desk trade
    createPinAccessTokenActionPIN-gated single-use access token

    Credit spend rate SSOT

    Fiat ledger debits must use the config multiplier — never the desk oracle.

    Fiat credit accounting rate
    FactTruth
    SSOTring-config.json → credit.unitToDefaultCurrency (usually 1)
    HelpersgetCreditUnitToDefaultCurrencyRate / getFiatCreditAccountingRate in lib/ring-config-core.ts + lib/payments/credit-currency.ts
    FallbackexchangeRates[defaultCurrency], then 1
    Ad-hoc debitWalletConductor.spendCredits (Server Action omits usdRate → conductor defaults to fiat helper)
    Store checkoutPaymentConductor internal_credit → internal-credit.processor.ts (also calls getFiatCreditAccountingRate)
    Neverplatform_settings.web3.oracle.ringPerUsd / getRingPerUsdRate for fiat usdRate
    Desk onlyring-token-oracle / pointsPerNativeToken for points ↔ RING

    Document POST /api/wallet/credit/spend only. A GET stub may return 410 in code — it is not a capability. Use getSpendSummary or GET /api/wallet/credit/history for reads.

    Action call pattern

    Server action auth gate

    HTTP routes (external / MCP)

    Wallet lifecycle

    MethodPathNotes
    GET/api/wallet/list{ wallets } via listWallets() — ?refresh=true force on-chain via refreshBalancesForUser (publishes wallet:list)
    POST/api/wallet/ensureIdempotent create-if-missing — ensureWallets publishes wallet:list when provisioning changes
    GET/api/wallet/balanceDefault wallet native-token balance

    Native-token operations

    MethodPathNotes
    GET/api/wallet/token/balance{ balance, address, chain, symbol }
    POST/api/wallet/token/transferCustodial native-token send; wallet_transactions row
    POST/api/wallet/transferExternal EVM custodial POL path when chains.enabled includes evm — not Solana native SSOT

    Activity

    MethodPathNotes
    GET/api/wallet/activityfilter=all|credit|chain, unified feed

    Credit ledger

    MethodPathNotes
    GET/api/wallet/credit/balanceBalance + spend limits — live UI via Tunnel credit:balance (publishToUserTunnel after ledger mutations)
    PUT/api/wallet/credit/balanceAdmin airdrop { user_id, amount, reason }
    POST/api/wallet/credit/topupOptional tx_hash verification
    POST/api/wallet/credit/spendDirect fiat debit via WalletConductor.spendCredits + unitToDefaultCurrency
    GET/api/wallet/credit/historyPaginated ledger

    Schemas: lib/zod/credit-schemas.ts. Service: features/wallet/services/credit-balance-service.ts.

    Solana desk

    MethodPathNotes
    GET/api/wallet/desk/quoteQuery side, amount
    POST/api/wallet/desk/execute{ idempotencyKey, quoteToken }

    SSOT file reference

    ConcernFileKey exports
    Credit CRUDfeatures/wallet/services/credit-balance-service.tsaddCredits, spendCredits, getCreditHistory
    Conductorfeatures/wallet/conductor/wallet-conductor.tsspendCredits, ensureNativeWallet
    Fiat ratelib/ring-config-core.ts / lib/payments/credit-currency.tsgetCreditUnitToDefaultCurrencyRate, getFiatCreditAccountingRate
    Store credit checkoutlib/payments/processors/internal-credit.processor.tscreateInternalCreditCheckout
    Gasless transfersfeatures/wallet/chains/native-token-transfer-service.tstransferNativeTokenForUser
    Desk tradesfeatures/wallet/chains/solana/desk-service.tsquoteDesk, executeDesk
    Native oraclefeatures/wallet/services/ring-token-oracle.tsgetRingPerUsdRate, setRingPerUsdRate
    Wallet DBlib/wallet/user-wallet-db.tsgetUserWallets, getNativeWallet
    PIN tokenslib/wallet/pin-access-token-db.tsissueAccessToken, consumeAccessToken

    Example — spend credits

    1. 1

      Prefer Server Action (React UI)

      Form fields: amount (required), description (optional — defaults to Credit spend), orderId (optional). Conductor applies getFiatCreditAccountingRate() when usdRate is omitted.

    2. 2

      Or HTTP POST (external / MCP)

      CreditSpendRequestSchema requires amount and description. Body may include optional order_id, reference_id, metadata.

    3. 3

      Store checkout (do not call spend HTTP from store UI)

      PaymentConductor rail internal_credit → internal-credit.processor.ts → creditBalanceService.spendCredits with the same fiat rate helper.

    Environment variables

    VariableRequiredUsed by
    WALLET_ENCRYPTION_KEYYesAES-256-GCM wallet secrets
    SOLANA_RPC_URLYesSolana RPC
    SOLANA_TREASURY_PRIVATE_KEYYesSponsored gas / treasury ops
    WALLET_ACCESS_TOKEN_TTL_SECONDSNo (default 900)PIN access tokens
    ORACLE_QUOTE_SECRETDeskQuote HMAC (falls back to WALLET_ENCRYPTION_KEY)
    RING_ORACLE_DEFAULT_RATENoDesk oracle fallback when DB disabled
    PLATFORM_SETTINGS_DISABLE_DBNoEnv-only oracle reads

    Desk oracle persistence (native token only)

    Desk oracle read path

    Admin write: setRingPerUsdRate or POST /api/admin/web3/settings.

    Authentication

    Prerequisite: crypto wallet provider + social login that provisions custodial wallets.

    Token Economics Setup

    See-also: desk oracle, transfer tax, first-settler discounts.

    Ethereum wallets (Wagmi v3)

    See-also: Wagmi pathNeedsWeb3 and getWalletBalance live in app/_actions/wallet.ts (dead get-wallet-balance.ts removed).

    executeDeskQuote
    Credit ↔ native desk trade
    createPinAccessTokenActionPIN-gated single-use access token

    Credit spend rate SSOT

    Fiat ledger debits must use the config multiplier — never the desk oracle.

    Fiat credit accounting rate
    FactTruth
    SSOTring-config.json → credit.unitToDefaultCurrency (usually 1)
    HelpersgetCreditUnitToDefaultCurrencyRate / getFiatCreditAccountingRate in lib/ring-config-core.ts + lib/payments/credit-currency.ts
    FallbackexchangeRates[defaultCurrency], then 1
    Ad-hoc debitWalletConductor.spendCredits (Server Action omits usdRate → conductor defaults to fiat helper)
    Store checkoutPaymentConductor internal_credit → internal-credit.processor.ts (also calls getFiatCreditAccountingRate)
    Neverplatform_settings.web3.oracle.ringPerUsd / getRingPerUsdRate for fiat usdRate
    Desk onlyring-token-oracle / pointsPerNativeToken for points ↔ RING

    Document POST /api/wallet/credit/spend only. A GET stub may return 410 in code — it is not a capability. Use getSpendSummary or GET /api/wallet/credit/history for reads.

    Action call pattern

    Server action auth gate

    HTTP routes (external / MCP)

    Wallet lifecycle

    MethodPathNotes
    GET/api/wallet/list{ wallets } via listWallets() — ?refresh=true force on-chain via refreshBalancesForUser (publishes wallet:list)
    POST/api/wallet/ensureIdempotent create-if-missing — ensureWallets publishes wallet:list when provisioning changes
    GET/api/wallet/balanceDefault wallet native-token balance

    Native-token operations

    MethodPathNotes
    GET/api/wallet/token/balance{ balance, address, chain, symbol }
    POST/api/wallet/token/transferCustodial native-token send; wallet_transactions row
    POST/api/wallet/transferExternal EVM custodial POL path when chains.enabled includes evm — not Solana native SSOT

    Activity

    MethodPathNotes
    GET/api/wallet/activityfilter=all|credit|chain, unified feed

    Credit ledger

    MethodPathNotes
    GET/api/wallet/credit/balanceBalance + spend limits — live UI via Tunnel credit:balance (publishToUserTunnel after ledger mutations)
    PUT/api/wallet/credit/balanceAdmin airdrop { user_id, amount, reason }
    POST/api/wallet/credit/topupOptional tx_hash verification
    POST/api/wallet/credit/spendDirect fiat debit via WalletConductor.spendCredits + unitToDefaultCurrency
    GET/api/wallet/credit/historyPaginated ledger

    Schemas: lib/zod/credit-schemas.ts. Service: features/wallet/services/credit-balance-service.ts.

    Solana desk

    MethodPathNotes
    GET/api/wallet/desk/quoteQuery side, amount
    POST/api/wallet/desk/execute{ idempotencyKey, quoteToken }

    SSOT file reference

    ConcernFileKey exports
    Credit CRUDfeatures/wallet/services/credit-balance-service.tsaddCredits, spendCredits, getCreditHistory
    Conductorfeatures/wallet/conductor/wallet-conductor.tsspendCredits, ensureNativeWallet
    Fiat ratelib/ring-config-core.ts / lib/payments/credit-currency.tsgetCreditUnitToDefaultCurrencyRate, getFiatCreditAccountingRate
    Store credit checkoutlib/payments/processors/internal-credit.processor.tscreateInternalCreditCheckout
    Gasless transfersfeatures/wallet/chains/native-token-transfer-service.tstransferNativeTokenForUser
    Desk tradesfeatures/wallet/chains/solana/desk-service.tsquoteDesk, executeDesk
    Native oraclefeatures/wallet/services/ring-token-oracle.tsgetRingPerUsdRate, setRingPerUsdRate
    Wallet DBlib/wallet/user-wallet-db.tsgetUserWallets, getNativeWallet
    PIN tokenslib/wallet/pin-access-token-db.tsissueAccessToken, consumeAccessToken

    Example — spend credits

    1. 1

      Prefer Server Action (React UI)

      Form fields: amount (required), description (optional — defaults to Credit spend), orderId (optional). Conductor applies getFiatCreditAccountingRate() when usdRate is omitted.

    2. 2

      Or HTTP POST (external / MCP)

      CreditSpendRequestSchema requires amount and description. Body may include optional order_id, reference_id, metadata.

    3. 3

      Store checkout (do not call spend HTTP from store UI)

      PaymentConductor rail internal_credit → internal-credit.processor.ts → creditBalanceService.spendCredits with the same fiat rate helper.

    Environment variables

    VariableRequiredUsed by
    WALLET_ENCRYPTION_KEYYesAES-256-GCM wallet secrets
    SOLANA_RPC_URLYesSolana RPC
    SOLANA_TREASURY_PRIVATE_KEYYesSponsored gas / treasury ops
    WALLET_ACCESS_TOKEN_TTL_SECONDSNo (default 900)PIN access tokens
    ORACLE_QUOTE_SECRETDeskQuote HMAC (falls back to WALLET_ENCRYPTION_KEY)
    RING_ORACLE_DEFAULT_RATENoDesk oracle fallback when DB disabled
    PLATFORM_SETTINGS_DISABLE_DBNoEnv-only oracle reads

    Desk oracle persistence (native token only)

    Desk oracle read path

    Admin write: setRingPerUsdRate or POST /api/admin/web3/settings.

    Authentication

    Prerequisite: crypto wallet provider + social login that provisions custodial wallets.

    Token Economics Setup

    See-also: desk oracle, transfer tax, first-settler discounts.

    Ethereum wallets (Wagmi v3)

    See-also: Wagmi pathNeedsWeb3 and getWalletBalance live in app/_actions/wallet.ts (dead get-wallet-balance.ts removed).