💎Spending Limits

Your safety net. Your budget enforcer. Your financial guardrails. Spending limits are what keep Yuki402's autonomous payments from becoming autonomous bankruptcy. Set them once, sleep soundly forever.

🎯 What Are Spending Limits?

The problem: Yuki pays autonomously. What if she goes rogue? What if you accidentally request 1000 AI images? What if a bug causes runaway spending?

The solution: Smart contract-enforced spending limits that are mathematically impossible to exceed.

Three time periods. Three caps. Total control:

Period	Timeframe	Purpose
Daily	24 hours	Prevents day-to-day overspending
Weekly	7 days	Caps weekly budget
Monthly	30 days	Long-term spending control

All limits enforced on-chain. Before every payment. No exceptions. No overrides.

🔒 How Limits Work (The Math)

The Hierarchy Rule

Limits must be nested logically:

Monthly ≥ Weekly ≥ Daily

✅ Valid Example:
Daily:   0.01 SOL
Weekly:  0.05 SOL  (5x daily)
Monthly: 0.2 SOL   (20x daily, 4x weekly)

❌ Invalid Example:
Daily:   0.1 SOL
Weekly:  0.05 SOL  ← Error! Less than daily
Monthly: 0.2 SOL

Why this matters: Prevents logical impossibilities. You can't spend more daily than weekly.

Automatic Resets

Limits reset automatically:

• Daily: Resets every 24 hours from first transaction of the day

• Weekly: Resets every 7 days from first weekly transaction

• Monthly: Resets every 30 days from first monthly transaction

Example:

First payment: Feb 3, 2026 @ 10:00 AM
Daily resets:  Feb 4, 2026 @ 10:00 AM
Weekly resets: Feb 10, 2026 @ 10:00 AM
Monthly resets: Mar 5, 2026 @ 10:00 AM

Resets are automatic. No manual intervention needed.

Real-Time Enforcement (The Checks)

Before EVERY payment, Yuki checks:

def can_process_payment(user, amount):
    # Check daily
    if user.daily_spent + amount > user.daily_limit:
        return False, "Daily limit exceeded"

    # Check weekly
    if user.weekly_spent + amount > user.weekly_limit:
        return False, "Weekly limit exceeded"

    # Check monthly
    if user.monthly_spent + amount > user.monthly_limit:
        return False, "Monthly limit exceeded"

    # All checks passed
    return True, "Payment approved"

If ANY check fails: Payment rejected. No money leaves your wallet.

If ALL checks pass: Payment processes.

Simple. Effective. Secure.

⚙️ Setting Up Limits

Recommended Starter Limits

Never used Yuki before? Start here:

🟢 Conservative (Recommended):
Daily:   0.01 SOL  (~$2.50)
Weekly:  0.05 SOL  (~$12.50)
Monthly: 0.2 SOL   (~$50)

Use case: Learning the system, occasional testing

Why conservative? Learn without risk. Scale up after you understand costs.

Limit Strategies by User Type

🟡 Moderate (Regular Users):

Daily:   0.02 SOL  (~$5)
Weekly:  0.1 SOL   (~$25)
Monthly: 0.4 SOL   (~$100)

Use case: Daily API access, routine automation

🟠 Aggressive (Power Users):

Daily:   0.1 SOL   (~$25)
Weekly:  0.5 SOL   (~$125)
Monthly: 2 SOL     (~$500)

Use case: Heavy usage, multiple services, production

🔴 Enterprise (Business/Teams):

Daily:   1 SOL     (~$250)
Weekly:  5 SOL     (~$1,250)
Monthly: 20 SOL    (~$5,000)

Use case: Production apps, team usage, high volume

Start conservative. Scale based on actual usage.

How to Set Limits (Smart Contract)

Limits are stored ON-CHAIN for maximum security:

// Set your limits via smart contract
function setLimits(
    uint256 dailyLimit,    // in wei/lamports
    uint256 weeklyLimit,   // in wei/lamports
    uint256 monthlyLimit   // in wei/lamports
) external

On-chain enforcement means:

• ✅ Cannot be bypassed

• ✅ Cannot be hacked

• ✅ Cannot be manipulated

• ✅ Transparent and auditable

Coming soon: Web UI for easy limit management (no Solidity required).

📊 Monitoring Your Spending

Current Usage Dashboard

Check anytime via Yuki chat or dashboard:

Daily Spending:
0.0035 / 0.01 SOL (35% used)
████████░░░░░░░░░░░░

Remaining today: 0.0065 SOL
Resets in: 14 hours 23 minutes

Weekly Spending:
0.015 / 0.05 SOL (30% used)
████████░░░░░░░░░░░░

Monthly Spending:
0.089 / 0.2 SOL (44.5% used)
████████████░░░░░░░░

Real-time visibility. No surprises.

Spending Trends

Historical analysis:

This Week:     0.015 SOL / 0.05 SOL (30%)
Last Week:     0.022 SOL (44%)
Average/Day:   0.003 SOL

Trend: ↓ Spending decreased 32% week-over-week

Track patterns. Optimize costs.

Alerts (Coming Soon)

Get notified when:

• 🟡 80% of any limit reached - "You've used 80% of your daily limit"

• 🔴 Limit exceeded - "Payment rejected: Daily limit exceeded"

• 🟠 Unusual pattern - "Spending spike detected: 3x normal daily average"

Stay informed. Stay in control.

🔄 Adjusting Limits

Increasing Limits

Need more capacity? Increase anytime:

Current daily: 0.01 SOL
New daily:     0.02 SOL

Effect: Immediately available for new payments
Note: Doesn't reset already-spent amount

Example:

Before increase:
Daily limit: 0.01 SOL
Spent today: 0.008 SOL
Remaining:   0.002 SOL

After increasing to 0.02 SOL:
Daily limit: 0.02 SOL
Spent today: 0.008 SOL (unchanged)
Remaining:   0.012 SOL ← New capacity

Instant effect. More runway immediately.

Decreasing Limits

Reduce your exposure:

Current daily: 0.1 SOL
New daily:     0.05 SOL

Effect: Future payments capped at new limit
Note: Doesn't affect already-spent amount

Example:

You've spent 0.08 SOL today (under old 0.1 limit)
You decrease limit to 0.05 SOL

Result: No more payments today (0.08 > 0.05)
Tomorrow: Resets, can spend up to 0.05 SOL

Decreasing limits = immediate spending freeze if you've exceeded new limit.

Temporary Overrides (Coming Soon)

One-time limit increase:

• Boost limit for 24 hours

• Requires additional wallet confirmation

• Automatically reverts after expiration

• Audit trail logged on-chain

Use case: "I need to generate 20 images today only, not every day."

🎬 Limit Scenarios (Real Examples)

Scenario 1: Within All Limits ✅

Daily Limit:  0.01 SOL
Spent Today:  0.007 SOL
New Payment:  0.002 SOL

Math:
0.007 + 0.002 = 0.009 SOL
0.009 ≤ 0.01 ✓

Result: ✅ Payment approved

Payment processes normally.

Scenario 2: Exceeds Daily Limit ❌

Daily Limit:  0.01 SOL
Spent Today:  0.009 SOL
New Payment:  0.003 SOL

Math:
0.009 + 0.003 = 0.012 SOL
0.012 > 0.01 ❌

Result: ❌ Payment rejected
Message: "Daily limit exceeded. Resets in 8 hours."

No money leaves your wallet. Wait for reset or increase limit.

Scenario 3: Daily OK, Weekly Exceeded ❌

Daily Limit:   0.05 SOL
Weekly Limit:  0.2 SOL
Spent Today:   0.01 SOL
Spent This Week: 0.19 SOL
New Payment:   0.03 SOL

Check Daily:
0.01 + 0.03 = 0.04 SOL
0.04 ≤ 0.05 ✓ (Daily OK)

Check Weekly:
0.19 + 0.03 = 0.22 SOL
0.22 > 0.2 ❌ (Weekly exceeded!)

Result: ❌ Payment rejected
Message: "Weekly limit exceeded. Resets in 3 days."

ALL limits must pass. One failure = rejection.

🔐 Smart Contract Security

The SpendingLimits Contract

Core functions enforcing your limits:

// Set limits (only wallet owner)
function setLimits(
    uint256 daily,
    uint256 weekly,
    uint256 monthly
) external onlyOwner

// Check if spending is allowed (called before every payment)
function canSpend(
    address user,
    uint256 amount
) public view returns (bool, string memory)

// Record spending (called after successful payment)
function recordSpending(
    address user,
    uint256 amount
) external onlyApprovedSpender

// Get remaining allowance
function getRemainingAllowance(
    address user
) public view returns (uint256 daily, uint256 weekly, uint256 monthly)

Approved Spenders

Authorize Yuki402 to check/record your spending:

// Approve Yuki402 contract
approveSpender(yuki402Address)

// Revoke approval anytime
revokeSpender(yuki402Address)

You control who can interact with your limits.

On-Chain Benefits

Why smart contracts > database:

Feature	Smart Contract	Traditional DB
Tamper-proof	✅ Immutable	❌ Can be edited
Transparent	✅ Public	❌ Opaque
Auditable	✅ On-chain	❌ Requires access
Decentralized	✅ No single point	❌ Centralized
Trustless	✅ Math enforced	❌ Trust required

Math > trust. Always.

✅ Best Practices

1. Start Small, Scale Gradually

Week 1:  0.01 SOL/day (learn the system)
Week 2:  0.02 SOL/day (comfortable with costs)
Week 3:  0.05 SOL/day (regular usage established)
Month 2: 0.1 SOL/day (power user mode)

Build confidence incrementally.

2. Review Weekly

Every Sunday (or pick your day):

✅ Check total spending ✅ Analyze per-service costs ✅ Look for unusual patterns ✅ Adjust limits if needed

5 minutes of review = complete peace of mind.

3. Use Separate Wallets

Consider multiple wallets for different purposes:

Testing Wallet:

• Daily: 0.005 SOL

• For experimental services

• Low risk

Production Wallet:

• Daily: 0.05 SOL

• For vetted, trusted services

• Medium risk

Cold Storage:

• No Yuki402 access

• Main holdings

• Zero risk

Separate concerns = better security.

4. Set Realistic Limits

Base limits on:

✅ Your budget - Can you afford to lose this? ✅ Expected usage - How much do you actually need? ✅ Service costs - What do services typically charge? ✅ Risk tolerance - How aggressive are you?

Example calculation:

Expected usage:
- Weather API: 0.001 SOL × 10 times/day = 0.01 SOL
- AI images: 0.005 SOL × 2 times/day = 0.01 SOL
- Storage: 0.0005 SOL × 5 times/day = 0.0025 SOL

Total daily need: 0.0225 SOL
Set daily limit: 0.025 SOL (with 10% buffer)

Math first. Guessing never.

5. Enable Alerts (When Available)

Turn on notifications for:

• 🟡 80% of limit reached

• 🔴 Limit exceeded

• 🟠 Unusual spending spike

• 🔵 Limit reset occurred

Proactive monitoring > reactive scrambling.

🔧 Troubleshooting

"Can't Set Limits"

Possible causes:

1. Wallet not connected

2. Invalid hierarchy (monthly < weekly)

3. Insufficient gas for transaction

4. Smart contract not approved

Solutions:

1. Connect wallet → Try again
2. Fix hierarchy: Monthly ≥ Weekly ≥ Daily
3. Add more SOL/ETH for gas
4. Approve spending limits contract

"Payment Rejected Despite Having Funds"

Check ALL three limits:

✓ Wallet balance: 1 SOL (sufficient)
✓ Daily limit: 0.008/0.01 SOL (within)
❌ Weekly limit: 0.049/0.05 SOL (payment would exceed!)
✓ Monthly limit: 0.15/0.2 SOL (within)

Result: Payment rejected due to weekly limit

All three must pass. One failure = no payment.

"Limits Not Updating"

Solution:

1. Wait for transaction confirmation (check block explorer)

2. Hard refresh page (Ctrl+Shift+R / Cmd+Shift+R)

3. Clear browser cache

4. Verify transaction succeeded on-chain

5. Contact support if issue persists

Blockchain is slow sometimes. Be patient.

🚀 Advanced Features (Coming Soon)

Multi-Signature Limits

For organizations/DAOs:

• Require 2-of-3 or 3-of-5 approvals for limit changes

• Prevents single point of failure

• Complete audit trail

• Enterprise-grade controls

Perfect for teams managing shared wallets.

Dynamic Limits

Time-based adjustments:

Business Hours (9am-5pm):
Daily limit: 0.1 SOL (higher capacity)

Off Hours (5pm-9am):
Daily limit: 0.01 SOL (reduced exposure)

Weekends:
Daily limit: 0.005 SOL (minimal spending)

Automatic adjustment based on time/day.

Spending Analysis Dashboard

AI-powered insights:

• Service breakdown (which services cost most?)

• Cost optimization suggestions

• Spending predictions ("at this rate, you'll hit monthly limit in 12 days")

• Anomaly detection

Data-driven spending optimization.

🛡️ Security Considerations

What Limits Protect Against

Even if someone gains unauthorized access, they CANNOT:

❌ Exceed your configured limits ❌ Modify your limits without wallet signature ❌ Bypass on-chain enforcement ❌ Drain your wallet

Limits are your last line of defense.

Smart Contract Audits

Our SpendingLimits contract is:

✅ Open source - View on GitHub ✅ Professionally audited - By top security firms ✅ Battle-tested - Used in production ✅ Upgradeable - With 48-hour timelock for security

Trust the math. Verify the code.

🔗 Related Documentation

• Autonomous Payments - How payments work

• Security Features - Complete security model

• Smart Contracts - Technical deep dive

• Best Practices - Pro tips

---

Questions about spending limits?

📧 Support: [email protected] 🐦 Updates: @yuki402xyz

Spending limits = peace of mind. Set them. Trust them. Sleep well.