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 server-only money facade for custodial native-token wallets and the fiat credit ledger. Thin adapters call the conductor; PaymentConductor owns PSP checkout for wallet_topup and native_token_onramp. Browser handoff after top-up is Conductor redirect + followCheckoutResult — see PaymentConductor architecture.
Operator / product guide: WalletConductor · Wallet · PaymentConductor
Use Founder / Developer tabs in the docs sidebar to filter this page. Feature overview (value + checklist): WalletConductor. HTTP/action inventory: Wallet API.
Capabilities, two-rate SSOT, operator checklist
Ledger, webhooks, purpose handlers
Actions and HTTP surface
nativePerMainCurrency) never rewrites store checkout or ad-hoc credit spend math (credit.creditBalanceUnitToMainCurrency).POST /api/wallet/transfer stay outside WalletConductor so clones do not mix rails accidentally.Depends-on: after transferNative / ensure, conductor fans out `wallet:list` via publishWalletListUpdate.
Next-step: dual-audience product guide for operators.
Same-workflow: PSP ledger and webhooks for wallet_topup / native_token_onramp.
See-also: member-facing wallet dashboard flows.
WalletConductor is Ring Platform's server-only money facade for custodial native-token wallets and the fiat credit ledger. Thin adapters call the conductor; PaymentConductor owns PSP checkout for wallet_topup and native_token_onramp. Browser handoff after top-up is Conductor redirect + followCheckoutResult — see PaymentConductor architecture.
Operator / product guide: WalletConductor · Wallet · PaymentConductor
Use Founder / Developer tabs in the docs sidebar to filter this page. Feature overview (value + checklist): WalletConductor. HTTP/action inventory: Wallet API.
Capabilities, two-rate SSOT, operator checklist
Ledger, webhooks, purpose handlers
Actions and HTTP surface
nativePerMainCurrency) never rewrites store checkout or ad-hoc credit spend math (credit.creditBalanceUnitToMainCurrency).POST /api/wallet/transfer stay outside WalletConductor so clones do not mix rails accidentally.Depends-on: after transferNative / ensure, conductor fans out `wallet:list` via publishWalletListUpdate.
Next-step: dual-audience product guide for operators.
Same-workflow: PSP ledger and webhooks for wallet_topup / native_token_onramp.
See-also: member-facing wallet dashboard flows.
WalletConductor is Ring Platform's server-only money facade for custodial native-token wallets and the fiat credit ledger. Thin adapters call the conductor; PaymentConductor owns PSP checkout for wallet_topup and native_token_onramp. Browser handoff after top-up is Conductor redirect + followCheckoutResult — see PaymentConductor architecture.
Operator / product guide: WalletConductor · Wallet · PaymentConductor
Use Founder / Developer tabs in the docs sidebar to filter this page. Feature overview (value + checklist): WalletConductor. HTTP/action inventory: Wallet API.
Capabilities, two-rate SSOT, operator checklist
Ledger, webhooks, purpose handlers
Actions and HTTP surface
nativePerMainCurrency) never rewrites store checkout or ad-hoc credit spend math (credit.creditBalanceUnitToMainCurrency).POST /api/wallet/transfer stay outside WalletConductor so clones do not mix rails accidentally.Depends-on: after transferNative / ensure, conductor fans out `wallet:list` via publishWalletListUpdate.
Next-step: dual-audience product guide for operators.
Same-workflow: PSP ledger and webhooks for wallet_topup / native_token_onramp.
See-also: member-facing wallet dashboard flows.
lib/payments/credit-balance.tsgetFiatCreditAccountingRatecredit.creditBalanceUnitToMainCurrency SSOT |
| Desk | features/wallet/chains/solana/desk-service.ts | Quote + execute (subscriber+) |
| Desk oracle | features/wallet/services/native-token-oracle.ts | nativePerMainCurrency for desk only |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts | Gasless native transfer |
| PSP checkout | lib/payments/conductor/payment-conductor.ts | wallet_topup, native_token_onramp |
| Onramp gate | lib/payments/confidential-token-onramp.ts | assertNativeTokenOnrampAllowed |
| Actions | app/_actions/wallet.ts | Session-facing wrappers |
| NFT buy | features/nft-market/services/solana-market-client.ts | Market purchase settlement |
| Method | Auth / gates | Delegates to |
|---|---|---|
initiateTopUp | Session; amount 25–2000 | PaymentConductor wallet_topup; returns redirect |
initiateNativeOnramp | Session + confidential+ + onramp flag | PaymentConductor native_token_onramp |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | desk-service + oracle |
getNativeBalance | Caller userId | native-token-transfer-service |
transferNative | Caller userId | transfer service + wallet_transactions + publishWalletListUpdate(userId, 'updated') |
spendCredits | Caller userId | creditBalanceService + fiat rate (+ credit:balance tunnel via service) |
ensureNativeWallet | Caller supplies id (OAuth-safe) | ensure-wallet (+ wallet:list when wallets change) |
ensureFunded | Session | ensure + optional credit floor |
purchaseNftListing | Idempotency key | SolanaMarketClient |
Also exported: getWalletConductorNativeChain() → getNativeChain().
| Rate | SSOT | Used by |
|---|---|---|
| Fiat credit accounting | credit.creditBalanceUnitToMainCurrency via getFiatCreditAccountingRate() | spendCredits, desk debit side, PaymentConductor credit_balance |
| Token Desk oracle | platform_settings.web3.oracle.nativePerMainCurrency | quoteDesk / executeDesk only |
Not owned by WalletConductor: store/membership checkout (store_order, membership_upgrade, credit_balance / native_token rails), SubscriptionConductor membership lifecycle, and external EVM POST /api/wallet/transfer (Polygon POL / SupportedCrypto). Prefer /api/wallet/token/transfer for platform native custodial sends.
app/_actions/wallet.ts)| Action | Conductor method |
|---|---|
ensureUserWallets | ensureNativeWallet |
getNativeTokenBalanceAction | getNativeBalance |
spendCredits | spendCredits |
transferNativeTokens | transferNative |
executeDeskQuote | executeDesk |
initiateCreditTopupPayment | initiateTopUp |
initiateNativeTokenOnrampPayment | initiateNativeOnramp |
createPinAccessTokenAction | ensureNativeWallet |
Desk quote has no action wrapper — HTTP only (POST /api/wallet/desk/quote). NFT buy: app/_actions/nft-market.ts → purchaseNftListing. OAuth: auth.ts → ensureNativeWallet.
| Method | Path | Conductor method |
|---|---|---|
POST | /api/wallet/desk/quote | quoteDesk |
POST | /api/wallet/desk/execute | executeDesk |
POST | /api/wallet/ensure | ensureNativeWallet |
GET | /api/wallet/token/balance | getNativeBalance |
POST | /api/wallet/token/transfer | transferNative |
POST | /api/wallet/credit/spend | spendCredits (fiat rate SSOT) |
| Path / surface | Why |
|---|---|
POST /api/wallet/transfer | EVM SupportedCrypto path — not Solana custodial SSOT |
POST /api/wallet/credit/topup | Chain-proof credit add via creditBalanceService (not card top-up) |
GET /api/wallet/credit/spend | 410 deprecated — use getSpendSummary / GET /api/wallet/credit/history |
| Store / membership PaymentConductor purposes | Checkout rails, not wallet facade |
See PaymentConductor architecture for CheckoutRedirect and WayForPay for HPP POST.
| Key | Role |
|---|---|
WALLET_ENCRYPTION_KEY | Custodial key encryption |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Custodial Solana + gas sponsorship |
CONFIDENTIAL_TOKEN_ONRAMP / NEXT_PUBLIC_CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Native card onramp gate (isNativeTokenOnrampEnabled) |
credit.creditBalanceUnitToMainCurrency | Fiat ledger accounting multiplier |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | Desk quote HMAC + fallback |
Server SSOT for onramp: lib/ring-config-chain.ts → isNativeTokenOnrampEnabled(). Runtime role gate: assertNativeTokenOnrampAllowed (confidential/admin/superadmin + flag).
getFiatCreditAccountingRate() — never feed desk nativePerMainCurrency into credit ledger debits/api/wallet/token/* — retired /api/wallet/ring/* aliases are removedDeep-dive: Server Actions and HTTP inventory.
lib/payments/credit-balance.tsgetFiatCreditAccountingRatecredit.creditBalanceUnitToMainCurrency SSOT |
| Desk | features/wallet/chains/solana/desk-service.ts | Quote + execute (subscriber+) |
| Desk oracle | features/wallet/services/native-token-oracle.ts | nativePerMainCurrency for desk only |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts | Gasless native transfer |
| PSP checkout | lib/payments/conductor/payment-conductor.ts | wallet_topup, native_token_onramp |
| Onramp gate | lib/payments/confidential-token-onramp.ts | assertNativeTokenOnrampAllowed |
| Actions | app/_actions/wallet.ts | Session-facing wrappers |
| NFT buy | features/nft-market/services/solana-market-client.ts | Market purchase settlement |
| Method | Auth / gates | Delegates to |
|---|---|---|
initiateTopUp | Session; amount 25–2000 | PaymentConductor wallet_topup; returns redirect |
initiateNativeOnramp | Session + confidential+ + onramp flag | PaymentConductor native_token_onramp |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | desk-service + oracle |
getNativeBalance | Caller userId | native-token-transfer-service |
transferNative | Caller userId | transfer service + wallet_transactions + publishWalletListUpdate(userId, 'updated') |
spendCredits | Caller userId | creditBalanceService + fiat rate (+ credit:balance tunnel via service) |
ensureNativeWallet | Caller supplies id (OAuth-safe) | ensure-wallet (+ wallet:list when wallets change) |
ensureFunded | Session | ensure + optional credit floor |
purchaseNftListing | Idempotency key | SolanaMarketClient |
Also exported: getWalletConductorNativeChain() → getNativeChain().
| Rate | SSOT | Used by |
|---|---|---|
| Fiat credit accounting | credit.creditBalanceUnitToMainCurrency via getFiatCreditAccountingRate() | spendCredits, desk debit side, PaymentConductor credit_balance |
| Token Desk oracle | platform_settings.web3.oracle.nativePerMainCurrency | quoteDesk / executeDesk only |
Not owned by WalletConductor: store/membership checkout (store_order, membership_upgrade, credit_balance / native_token rails), SubscriptionConductor membership lifecycle, and external EVM POST /api/wallet/transfer (Polygon POL / SupportedCrypto). Prefer /api/wallet/token/transfer for platform native custodial sends.
app/_actions/wallet.ts)| Action | Conductor method |
|---|---|
ensureUserWallets | ensureNativeWallet |
getNativeTokenBalanceAction | getNativeBalance |
spendCredits | spendCredits |
transferNativeTokens | transferNative |
executeDeskQuote | executeDesk |
initiateCreditTopupPayment | initiateTopUp |
initiateNativeTokenOnrampPayment | initiateNativeOnramp |
createPinAccessTokenAction | ensureNativeWallet |
Desk quote has no action wrapper — HTTP only (POST /api/wallet/desk/quote). NFT buy: app/_actions/nft-market.ts → purchaseNftListing. OAuth: auth.ts → ensureNativeWallet.
| Method | Path | Conductor method |
|---|---|---|
POST | /api/wallet/desk/quote | quoteDesk |
POST | /api/wallet/desk/execute | executeDesk |
POST | /api/wallet/ensure | ensureNativeWallet |
GET | /api/wallet/token/balance | getNativeBalance |
POST | /api/wallet/token/transfer | transferNative |
POST | /api/wallet/credit/spend | spendCredits (fiat rate SSOT) |
| Path / surface | Why |
|---|---|
POST /api/wallet/transfer | EVM SupportedCrypto path — not Solana custodial SSOT |
POST /api/wallet/credit/topup | Chain-proof credit add via creditBalanceService (not card top-up) |
GET /api/wallet/credit/spend | 410 deprecated — use getSpendSummary / GET /api/wallet/credit/history |
| Store / membership PaymentConductor purposes | Checkout rails, not wallet facade |
See PaymentConductor architecture for CheckoutRedirect and WayForPay for HPP POST.
| Key | Role |
|---|---|
WALLET_ENCRYPTION_KEY | Custodial key encryption |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Custodial Solana + gas sponsorship |
CONFIDENTIAL_TOKEN_ONRAMP / NEXT_PUBLIC_CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Native card onramp gate (isNativeTokenOnrampEnabled) |
credit.creditBalanceUnitToMainCurrency | Fiat ledger accounting multiplier |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | Desk quote HMAC + fallback |
Server SSOT for onramp: lib/ring-config-chain.ts → isNativeTokenOnrampEnabled(). Runtime role gate: assertNativeTokenOnrampAllowed (confidential/admin/superadmin + flag).
getFiatCreditAccountingRate() — never feed desk nativePerMainCurrency into credit ledger debits/api/wallet/token/* — retired /api/wallet/ring/* aliases are removedDeep-dive: Server Actions and HTTP inventory.
lib/payments/credit-balance.tsgetFiatCreditAccountingRatecredit.creditBalanceUnitToMainCurrency SSOT |
| Desk | features/wallet/chains/solana/desk-service.ts | Quote + execute (subscriber+) |
| Desk oracle | features/wallet/services/native-token-oracle.ts | nativePerMainCurrency for desk only |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts | Gasless native transfer |
| PSP checkout | lib/payments/conductor/payment-conductor.ts | wallet_topup, native_token_onramp |
| Onramp gate | lib/payments/confidential-token-onramp.ts | assertNativeTokenOnrampAllowed |
| Actions | app/_actions/wallet.ts | Session-facing wrappers |
| NFT buy | features/nft-market/services/solana-market-client.ts | Market purchase settlement |
| Method | Auth / gates | Delegates to |
|---|---|---|
initiateTopUp | Session; amount 25–2000 | PaymentConductor wallet_topup; returns redirect |
initiateNativeOnramp | Session + confidential+ + onramp flag | PaymentConductor native_token_onramp |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | desk-service + oracle |
getNativeBalance | Caller userId | native-token-transfer-service |
transferNative | Caller userId | transfer service + wallet_transactions + publishWalletListUpdate(userId, 'updated') |
spendCredits | Caller userId | creditBalanceService + fiat rate (+ credit:balance tunnel via service) |
ensureNativeWallet | Caller supplies id (OAuth-safe) | ensure-wallet (+ wallet:list when wallets change) |
ensureFunded | Session | ensure + optional credit floor |
purchaseNftListing | Idempotency key | SolanaMarketClient |
Also exported: getWalletConductorNativeChain() → getNativeChain().
| Rate | SSOT | Used by |
|---|---|---|
| Fiat credit accounting | credit.creditBalanceUnitToMainCurrency via getFiatCreditAccountingRate() | spendCredits, desk debit side, PaymentConductor credit_balance |
| Token Desk oracle | platform_settings.web3.oracle.nativePerMainCurrency | quoteDesk / executeDesk only |
Not owned by WalletConductor: store/membership checkout (store_order, membership_upgrade, credit_balance / native_token rails), SubscriptionConductor membership lifecycle, and external EVM POST /api/wallet/transfer (Polygon POL / SupportedCrypto). Prefer /api/wallet/token/transfer for platform native custodial sends.
app/_actions/wallet.ts)| Action | Conductor method |
|---|---|
ensureUserWallets | ensureNativeWallet |
getNativeTokenBalanceAction | getNativeBalance |
spendCredits | spendCredits |
transferNativeTokens | transferNative |
executeDeskQuote | executeDesk |
initiateCreditTopupPayment | initiateTopUp |
initiateNativeTokenOnrampPayment | initiateNativeOnramp |
createPinAccessTokenAction | ensureNativeWallet |
Desk quote has no action wrapper — HTTP only (POST /api/wallet/desk/quote). NFT buy: app/_actions/nft-market.ts → purchaseNftListing. OAuth: auth.ts → ensureNativeWallet.
| Method | Path | Conductor method |
|---|---|---|
POST | /api/wallet/desk/quote | quoteDesk |
POST | /api/wallet/desk/execute | executeDesk |
POST | /api/wallet/ensure | ensureNativeWallet |
GET | /api/wallet/token/balance | getNativeBalance |
POST | /api/wallet/token/transfer | transferNative |
POST | /api/wallet/credit/spend | spendCredits (fiat rate SSOT) |
| Path / surface | Why |
|---|---|
POST /api/wallet/transfer | EVM SupportedCrypto path — not Solana custodial SSOT |
POST /api/wallet/credit/topup | Chain-proof credit add via creditBalanceService (not card top-up) |
GET /api/wallet/credit/spend | 410 deprecated — use getSpendSummary / GET /api/wallet/credit/history |
| Store / membership PaymentConductor purposes | Checkout rails, not wallet facade |
See PaymentConductor architecture for CheckoutRedirect and WayForPay for HPP POST.
| Key | Role |
|---|---|
WALLET_ENCRYPTION_KEY | Custodial key encryption |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Custodial Solana + gas sponsorship |
CONFIDENTIAL_TOKEN_ONRAMP / NEXT_PUBLIC_CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Native card onramp gate (isNativeTokenOnrampEnabled) |
credit.creditBalanceUnitToMainCurrency | Fiat ledger accounting multiplier |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | Desk quote HMAC + fallback |
Server SSOT for onramp: lib/ring-config-chain.ts → isNativeTokenOnrampEnabled(). Runtime role gate: assertNativeTokenOnrampAllowed (confidential/admin/superadmin + flag).
getFiatCreditAccountingRate() — never feed desk nativePerMainCurrency into credit ledger debits/api/wallet/token/* — retired /api/wallet/ring/* aliases are removedDeep-dive: Server Actions and HTTP inventory.