Yukkai Wallet
The Yukkai Wallet is the credit system tied to your Yukkai account key — it tracks your balance, usage across all Yukkai-billed services, and transaction history.
The Yukkai Wallet is the balance/credit system tied to a Yukkai account key (yk_...). It tracks the money you deposit (via Stripe) and the money you spend across every AI provider Yukkai bills on your behalf — chat models, image/video/music generation, and more.
What is the Yukkai Wallet?
The Wallet is a ledger between:
- Money you deposit — via Stripe credit packs ($10 to $1000).
- Money you spend — across all Yukkai-billed AI services.
- Balance — displayed in USD (stored internally in nanodollars: 1 USD = 1,000,000,000 nano).
- Usage — across all Yukkai-billed provider spend.
- Transaction history — purchases, child key allocations, child key refunds.
What the Wallet Covers
The Wallet tracks spend across every AI provider Yukkai bills on your behalf — not just Fusion/Frontier. This includes:
- Chat models — Yukkai Fusion, Yukkai Frontier.
- Media generation — image, video, and music generation (via Google models).
- Direct provider calls — when Yukkai uses its own account/keys to service your request.
- Aggregator calls — OpenRouter, Eden AI, Replicate, Fal.ai, etc., when Yukkai is footing the bill.
What the Wallet Does NOT Cover
yukkai/freeusage — Free has its own separate daily/monthly quota and doesn't debit the Wallet.- Personal OpenRouter key spend — if you're using your own
sk-or-...key, that spend happens entirely outside Yukkai, against your own OpenRouter account, and never appears in this ledger.
How to Check Your Balance
In Settings
- Go to Settings → Credits.
- Your current balance is displayed at the top.
- Below that, you'll see:
- Low-balance warning (if applicable).
- Full transaction history.
- "Add Credits" button.
Via the Wallet Button
Click the Wallet button in the top-right corner of the app to see your balance and quick access to the Credits screen.
Topping Up
How to Add Credits
- Go to Settings → Credits.
- Click Add Credits.
- Choose a credit pack (roughly $10 to $1000).
- The app opens Stripe checkout in your system browser.
- Complete the payment.
- A backend webhook confirms payment.
- The app polls/refreshes your balance automatically.
Important Notes
- Stripe only — there's no in-app purchase (no StoreKit) and no embedded payment form.
- System browser — the checkout opens in your default browser, not inside the app.
- Automatic confirmation — once payment completes, your balance updates automatically (you don't need to manually refresh).
Never Suggest Other Payment Methods
There is no other supported payment path — never suggest topping up via anything other than the in-app Stripe flow.
Transaction History
The Wallet tracks all transactions:
| Type | Description |
|---|---|
| credit | A purchase (adding funds to your Wallet). |
| child-allocation | You created a child key and allocated part of your Wallet balance as its budget. |
| child-refund | You killed a child key and its unused budget was refunded to the Wallet. |
You can view the full history in Settings → Credits.
Low Balance Warnings
When your balance is low, Yukkai will show a warning in Settings → Credits. If your balance reaches zero:
- Fusion/Frontier requests will fail with an HTTP 402 (Payment Required) error.
- Media generation requests will also fail with 402.
- Yukkai Free will continue to work (it has a separate quota).
- Personal OpenRouter key requests are unaffected (they don't use the Wallet).
What Uses Wallet Credits?
Depending on the service, credits may be used for:
- Yukkai Fusion — automatic model routing for everyday tasks.
- Yukkai Frontier — premium model routing for complex tasks.
- Image generation — via Google Gemini image models.
- Video generation — via Google Veo models.
- Music generation — via Google Lyria models.
- Other providers billed through Yukkai — when Yukkai uses its own keys to service a request.
- Child Yukkai API keys — created from the Wallet and used directly in your other apps.
Wallet vs. Personal OpenRouter Key
| Yukkai Wallet | Personal OpenRouter Key | |
|---|---|---|
| Billing entity | Yukkai | OpenRouter |
| Top-up method | Stripe (in-app) | OpenRouter website |
| Balance visible in Yukkai | ✅ Yes | ❌ No |
| Usage tracked in Yukkai | ✅ Yes | ❌ No |
| "Add Credits" button | Opens Stripe checkout | Redirects to openrouter.ai |
| Child keys | ✅ Supported | ❌ Not supported |
Rules and Common Mistakes
✅ Do
- Check your Wallet balance in Settings → Credits.
- Top up via the in-app Stripe flow.
- Understand that the Wallet covers all Yukkai-billed services (not just Fusion/Frontier).
- Use the Wallet button in the top-right for quick balance checks.
❌ Don't
- Don't assume the Wallet only tracks Fusion/Frontier — it covers all Yukkai-billed spend, across direct providers and aggregators alike.
- Don't assume personal OpenRouter keys have a Yukkai Wallet — they don't;
canPurchaseCreditsis true only for the Yukkai provider. - Don't expect the Wallet to reflect a personal OpenRouter key's balance — that's invisible to Yukkai entirely.
- Don't describe top-up as an App Store in-app purchase — it's Stripe, in the system browser.
- Don't describe
yukkai/freeas consuming Wallet balance — it has a separate free quota.
Examples
User asks about balance
User: "How much credit do I have left?"
Yukkai: "You can check your Yukkai Wallet balance in Settings → Credits. Your current balance is displayed at the top, along with your full transaction history."
User asks how to add credits
User: "How do I add more credits?"
Yukkai: "Go to Settings → Credits and click 'Add Credits'. Choose a credit pack ($10 to $1000), and the app will open Stripe checkout in your browser. Once you complete the payment, your balance will update automatically."
User asks why media generation failed
User: "I tried to generate an image but got an error."
Yukkai: "Image generation is billed to your Yukkai Wallet. If your balance is too low, the request will fail with an HTTP 402 error. Check your balance in Settings → Credits and top up if needed."
User asks about Free model
User: "Does using Yukkai Free consume my Wallet balance?"
Yukkai: "No — Yukkai Free has its own separate daily/monthly usage limit and doesn't deduct anything from your Wallet balance. It's completely free to use."
User is using a personal OpenRouter key
User: "Why doesn't my Wallet show my usage?"
Yukkai: "You're using a personal OpenRouter key, which means your spend is billed directly by OpenRouter, not by Yukkai. Your OpenRouter usage won't appear in the Yukkai Wallet — you can check it on the OpenRouter website instead."
Good to Know
- The Wallet is Yukkai-account-only — personal OpenRouter keys don't have a Wallet.
- All Yukkai-billed services draw from the same balance — Fusion, Frontier, media generation, and more.
- Stripe is the only payment method — no StoreKit, no embedded forms.
- Balance updates automatically — no manual refresh needed after topping up.
- Child keys allocate from the Wallet — creating a child key reserves part of your balance as its budget.
Learn More
- Account Key — Understanding your
yk_...master key. - Child API Keys — Creating bounded sub-keys from your Wallet.
- Recharging Credits — Detailed guide to topping up.
- Error Codes — Understanding HTTP 402 and other billing errors.