Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
WalletConductor is Ring Platform's orchestration facade for custodial native-token web3 and fiat credit money paths. Thin adapters (app/_actions/wallet.ts, /api/wallet/token/*, /api/wallet/desk/*, NFT market buy) call the conductor; it delegates PSPs to PaymentConductor and ledger math to creditBalanceService.
Use Founder / Developer tabs in the docs sidebar to filter this page. Member-facing product UI: Wallet. HTTP/action inventory: Wallet API.
One layer for wallet money: card → credit points, desk → native token, gasless custodial sends, ad-hoc credit spend, and NFT market purchases. Fiat spend accounting uses credit.creditBalanceUnitToMainCurrency (usually 1) — never the desk oracle. External EVM POL/USDT via POST /api/wallet/transfer stays outside this conductor.
| Capability | Method | Result |
|---|---|---|
| Card → credit points | initiateTopUp | PaymentConductor wallet_topup → fiat ledger credit |
| Card/PayPal → treasury native | initiateNativeOnramp | PaymentConductor native_token_onramp (confidential+) |
| Token Desk | quoteDesk / executeDesk | Credit points ↔ native at desk oracle (subscriber+) |
| Custodial send | transferNative | Gasless native transfer + wallet_transactions row |
| Native balance | getNativeBalance | Custodial balance for platform native chain |
| Ad-hoc credit spend | spendCredits | Fiat ledger debit at creditBalanceUnitToMainCurrency |
Not in WalletConductor: store/membership checkout debit (PaymentConductor credit_balance / SubscriptionConductor), and external EVM POST /api/wallet/transfer. Those remain separate SSOT paths by design.
| Rate | SSOT | Used by |
|---|---|---|
| Fiat credit accounting | ring-config.json → credit.creditBalanceUnitToMainCurrency (usually 1) via getMainCurrencyCreditAccountingRate() | spendCredits, desk debit side, credit_balance checkout |
| Token Desk oracle | platform_settings.web3.oracle.nativePerMainCurrency via native-token-oracle.ts | quoteDesk / executeDesk points ↔ native only |
WalletConductor is the operator-facing money spine behind the Wallet product. Members see top-up, desk, and send UI; your clone stays coherent because every path hits one facade — not scattered PSP and ledger calls.
Any signed-in member buys credit points with a card. Points are fiat ledger units (1:1 with store mainCurrency when creditBalanceUnitToMainCurrency is 1).
Subscriber+ converts points ↔ native at the desk oracle. Changing nativePerMainCurrency never rewrites store or ad-hoc credit spend math.
Confidential+ card/PayPal → treasury native (feature-flagged). Does not add credit points.
WalletConductor is Ring Platform's orchestration facade for custodial native-token web3 and fiat credit money paths. Thin adapters (app/_actions/wallet.ts, /api/wallet/token/*, /api/wallet/desk/*, NFT market buy) call the conductor; it delegates PSPs to PaymentConductor and ledger math to creditBalanceService.
Use Founder / Developer tabs in the docs sidebar to filter this page. Member-facing product UI: Wallet. HTTP/action inventory: Wallet API.
One layer for wallet money: card → credit points, desk → native token, gasless custodial sends, ad-hoc credit spend, and NFT market purchases. Fiat spend accounting uses credit.creditBalanceUnitToMainCurrency (usually 1) — never the desk oracle. External EVM POL/USDT via POST /api/wallet/transfer stays outside this conductor.
| Capability | Method | Result |
|---|---|---|
| Card → credit points | initiateTopUp | PaymentConductor wallet_topup → fiat ledger credit |
| Card/PayPal → treasury native | initiateNativeOnramp | PaymentConductor native_token_onramp (confidential+) |
| Token Desk | quoteDesk / executeDesk | Credit points ↔ native at desk oracle (subscriber+) |
| Custodial send | transferNative | Gasless native transfer + wallet_transactions row |
| Native balance | getNativeBalance | Custodial balance for platform native chain |
| Ad-hoc credit spend | spendCredits | Fiat ledger debit at creditBalanceUnitToMainCurrency |
Not in WalletConductor: store/membership checkout debit (PaymentConductor credit_balance / SubscriptionConductor), and external EVM POST /api/wallet/transfer. Those remain separate SSOT paths by design.
| Rate | SSOT | Used by |
|---|---|---|
| Fiat credit accounting | ring-config.json → credit.creditBalanceUnitToMainCurrency (usually 1) via getMainCurrencyCreditAccountingRate() | spendCredits, desk debit side, credit_balance checkout |
| Token Desk oracle | platform_settings.web3.oracle.nativePerMainCurrency via native-token-oracle.ts | quoteDesk / executeDesk points ↔ native only |
WalletConductor is the operator-facing money spine behind the Wallet product. Members see top-up, desk, and send UI; your clone stays coherent because every path hits one facade — not scattered PSP and ledger calls.
Any signed-in member buys credit points with a card. Points are fiat ledger units (1:1 with store mainCurrency when creditBalanceUnitToMainCurrency is 1).
Subscriber+ converts points ↔ native at the desk oracle. Changing nativePerMainCurrency never rewrites store or ad-hoc credit spend math.
Confidential+ card/PayPal → treasury native (feature-flagged). Does not add credit points.
WalletConductor is Ring Platform's orchestration facade for custodial native-token web3 and fiat credit money paths. Thin adapters (app/_actions/wallet.ts, /api/wallet/token/*, /api/wallet/desk/*, NFT market buy) call the conductor; it delegates PSPs to PaymentConductor and ledger math to creditBalanceService.
Use Founder / Developer tabs in the docs sidebar to filter this page. Member-facing product UI: Wallet. HTTP/action inventory: Wallet API.
One layer for wallet money: card → credit points, desk → native token, gasless custodial sends, ad-hoc credit spend, and NFT market purchases. Fiat spend accounting uses credit.creditBalanceUnitToMainCurrency (usually 1) — never the desk oracle. External EVM POL/USDT via POST /api/wallet/transfer stays outside this conductor.
| Capability | Method | Result |
|---|---|---|
| Card → credit points | initiateTopUp | PaymentConductor wallet_topup → fiat ledger credit |
| Card/PayPal → treasury native | initiateNativeOnramp | PaymentConductor native_token_onramp (confidential+) |
| Token Desk | quoteDesk / executeDesk | Credit points ↔ native at desk oracle (subscriber+) |
| Custodial send | transferNative | Gasless native transfer + wallet_transactions row |
| Native balance | getNativeBalance | Custodial balance for platform native chain |
| Ad-hoc credit spend | spendCredits | Fiat ledger debit at creditBalanceUnitToMainCurrency |
Not in WalletConductor: store/membership checkout debit (PaymentConductor credit_balance / SubscriptionConductor), and external EVM POST /api/wallet/transfer. Those remain separate SSOT paths by design.
| Rate | SSOT | Used by |
|---|---|---|
| Fiat credit accounting | ring-config.json → credit.creditBalanceUnitToMainCurrency (usually 1) via getMainCurrencyCreditAccountingRate() | spendCredits, desk debit side, credit_balance checkout |
| Token Desk oracle | platform_settings.web3.oracle.nativePerMainCurrency via native-token-oracle.ts | quoteDesk / executeDesk points ↔ native only |
WalletConductor is the operator-facing money spine behind the Wallet product. Members see top-up, desk, and send UI; your clone stays coherent because every path hits one facade — not scattered PSP and ledger calls.
Any signed-in member buys credit points with a card. Points are fiat ledger units (1:1 with store mainCurrency when creditBalanceUnitToMainCurrency is 1).
Subscriber+ converts points ↔ native at the desk oracle. Changing nativePerMainCurrency never rewrites store or ad-hoc credit spend math.
Confidential+ card/PayPal → treasury native (feature-flagged). Does not add credit points.
| Wallet provision |
ensureNativeWallet |
| Atomic multi-chain wallets (OAuth-safe, no session) |
| Min credit gate | ensureFunded | Session-gated provision + credit floor |
| NFT market buy | purchaseNftListing | Idempotent RING buy via Solana market client |
Confirm credit unit SSOT
Keep credit.creditBalanceUnitToMainCurrency: 1 in ring-config.json unless you intentionally scale points vs fiat. Desk oracle changes never affect store checkout or POST /api/wallet/credit/spend.
Separate desk oracle from fiat
Superadmins set nativePerMainCurrency for desk conversion only. Do not expect that rate on ad-hoc credit spend.
Gate native onramp carefully
Native card onramp is confidential+ and feature-flagged (CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp). Leave it off until treasury ops and compliance are ready.
Prefer Server Actions from UI. Keep HTTP wallet routes for MCP and non-React clients. Prefer /api/wallet/token/* — retired /api/wallet/ring/* aliases are removed.
features/wallet/services/ensure-wallet.ts| Credit ledger | features/wallet/services/credit-balance-service.ts |
| Fiat rate | lib/ring-config-core.ts → getCreditUnitToMainCurrencyRate / lib/payments/credit-balance.ts → getMainCurrencyCreditAccountingRate |
| Desk | features/wallet/chains/solana/desk-service.ts |
| Desk oracle | features/wallet/services/native-token-oracle.ts |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts |
| PSP checkout | lib/payments/conductor/payment-conductor.ts |
| Store credit rail | lib/payments/processors/credit-balance.processor.ts (PaymentConductor — not WC) |
| Actions | app/_actions/wallet.ts |
| NFT buy | features/nft-market/services/solana-market-client.ts |
| Method | Auth / gates | Notes |
|---|---|---|
ensureNativeWallet | Caller supplies id | OAuth-safe; returns { ok, native, wallets } |
ensureFunded | Session | Provisions + optional credit minimum |
initiateTopUp | Session | Amount 25–2000; purpose wallet_topup |
initiateNativeOnramp | Session + confidential metadata | Optional processor paypal/stripe/wayforpay |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | Solana desk SSOT |
transferNative | Caller supplies userId | Writes wallet_transactions; touches contacts |
spendCredits | Caller supplies userId | Defaults usdRate to getMainCurrencyCreditAccountingRate() |
purchaseNftListing | Idempotency key | Status: pending → submitted → confirmed / failed |
getNativeBalance | Caller supplies userId | Thin wrap of transfer service |
Card tab omits processor (env SSOT). PayPal tab sets processor=paypal. Client: lib/payments/checkout-redirect.ts.
| Key | Role |
|---|---|
WALLET_ENCRYPTION_KEY | Custodial key encryption |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Custodial Solana + gas sponsorship |
CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Native card onramp gate |
credit.creditBalanceUnitToMainCurrency | Fiat ledger accounting multiplier |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | Desk quote HMAC + fallback |
PSP rails used by top-up and onramp.
| Wallet provision |
ensureNativeWallet |
| Atomic multi-chain wallets (OAuth-safe, no session) |
| Min credit gate | ensureFunded | Session-gated provision + credit floor |
| NFT market buy | purchaseNftListing | Idempotent RING buy via Solana market client |
Confirm credit unit SSOT
Keep credit.creditBalanceUnitToMainCurrency: 1 in ring-config.json unless you intentionally scale points vs fiat. Desk oracle changes never affect store checkout or POST /api/wallet/credit/spend.
Separate desk oracle from fiat
Superadmins set nativePerMainCurrency for desk conversion only. Do not expect that rate on ad-hoc credit spend.
Gate native onramp carefully
Native card onramp is confidential+ and feature-flagged (CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp). Leave it off until treasury ops and compliance are ready.
Prefer Server Actions from UI. Keep HTTP wallet routes for MCP and non-React clients. Prefer /api/wallet/token/* — retired /api/wallet/ring/* aliases are removed.
features/wallet/services/ensure-wallet.ts| Credit ledger | features/wallet/services/credit-balance-service.ts |
| Fiat rate | lib/ring-config-core.ts → getCreditUnitToMainCurrencyRate / lib/payments/credit-balance.ts → getMainCurrencyCreditAccountingRate |
| Desk | features/wallet/chains/solana/desk-service.ts |
| Desk oracle | features/wallet/services/native-token-oracle.ts |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts |
| PSP checkout | lib/payments/conductor/payment-conductor.ts |
| Store credit rail | lib/payments/processors/credit-balance.processor.ts (PaymentConductor — not WC) |
| Actions | app/_actions/wallet.ts |
| NFT buy | features/nft-market/services/solana-market-client.ts |
| Method | Auth / gates | Notes |
|---|---|---|
ensureNativeWallet | Caller supplies id | OAuth-safe; returns { ok, native, wallets } |
ensureFunded | Session | Provisions + optional credit minimum |
initiateTopUp | Session | Amount 25–2000; purpose wallet_topup |
initiateNativeOnramp | Session + confidential metadata | Optional processor paypal/stripe/wayforpay |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | Solana desk SSOT |
transferNative | Caller supplies userId | Writes wallet_transactions; touches contacts |
spendCredits | Caller supplies userId | Defaults usdRate to getMainCurrencyCreditAccountingRate() |
purchaseNftListing | Idempotency key | Status: pending → submitted → confirmed / failed |
getNativeBalance | Caller supplies userId | Thin wrap of transfer service |
Card tab omits processor (env SSOT). PayPal tab sets processor=paypal. Client: lib/payments/checkout-redirect.ts.
| Key | Role |
|---|---|
WALLET_ENCRYPTION_KEY | Custodial key encryption |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Custodial Solana + gas sponsorship |
CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Native card onramp gate |
credit.creditBalanceUnitToMainCurrency | Fiat ledger accounting multiplier |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | Desk quote HMAC + fallback |
PSP rails used by top-up and onramp.
| Wallet provision |
ensureNativeWallet |
| Atomic multi-chain wallets (OAuth-safe, no session) |
| Min credit gate | ensureFunded | Session-gated provision + credit floor |
| NFT market buy | purchaseNftListing | Idempotent RING buy via Solana market client |
Confirm credit unit SSOT
Keep credit.creditBalanceUnitToMainCurrency: 1 in ring-config.json unless you intentionally scale points vs fiat. Desk oracle changes never affect store checkout or POST /api/wallet/credit/spend.
Separate desk oracle from fiat
Superadmins set nativePerMainCurrency for desk conversion only. Do not expect that rate on ad-hoc credit spend.
Gate native onramp carefully
Native card onramp is confidential+ and feature-flagged (CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp). Leave it off until treasury ops and compliance are ready.
Prefer Server Actions from UI. Keep HTTP wallet routes for MCP and non-React clients. Prefer /api/wallet/token/* — retired /api/wallet/ring/* aliases are removed.
features/wallet/services/ensure-wallet.ts| Credit ledger | features/wallet/services/credit-balance-service.ts |
| Fiat rate | lib/ring-config-core.ts → getCreditUnitToMainCurrencyRate / lib/payments/credit-balance.ts → getMainCurrencyCreditAccountingRate |
| Desk | features/wallet/chains/solana/desk-service.ts |
| Desk oracle | features/wallet/services/native-token-oracle.ts |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts |
| PSP checkout | lib/payments/conductor/payment-conductor.ts |
| Store credit rail | lib/payments/processors/credit-balance.processor.ts (PaymentConductor — not WC) |
| Actions | app/_actions/wallet.ts |
| NFT buy | features/nft-market/services/solana-market-client.ts |
| Method | Auth / gates | Notes |
|---|---|---|
ensureNativeWallet | Caller supplies id | OAuth-safe; returns { ok, native, wallets } |
ensureFunded | Session | Provisions + optional credit minimum |
initiateTopUp | Session | Amount 25–2000; purpose wallet_topup |
initiateNativeOnramp | Session + confidential metadata | Optional processor paypal/stripe/wayforpay |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | Solana desk SSOT |
transferNative | Caller supplies userId | Writes wallet_transactions; touches contacts |
spendCredits | Caller supplies userId | Defaults usdRate to getMainCurrencyCreditAccountingRate() |
purchaseNftListing | Idempotency key | Status: pending → submitted → confirmed / failed |
getNativeBalance | Caller supplies userId | Thin wrap of transfer service |
Card tab omits processor (env SSOT). PayPal tab sets processor=paypal. Client: lib/payments/checkout-redirect.ts.
| Key | Role |
|---|---|
WALLET_ENCRYPTION_KEY | Custodial key encryption |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Custodial Solana + gas sponsorship |
CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Native card onramp gate |
credit.creditBalanceUnitToMainCurrency | Fiat ledger accounting multiplier |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | Desk quote HMAC + fallback |
PSP rails used by top-up and onramp.