Create Your First Budget

Overview

Budgets are spending limits you set for AI agents or specific purposes. They're enforced by blockchain smart contracts, giving you complete control over how much your agents can spend and who they can pay.

This guide covers:

Understanding how budgets work

Creating your first budget

Syncing to the blockchain (critical step!)

Managing recipients

Adding tools and generating credentials

How Budgets Work

Budget + Smart Contract = Secure Spending

When you create a budget, it exists in two places:

1. Your Dashboard (Database)

Fast to update and easy to manage

Shows your preferences immediately

Convenient for configuration

2. The Blockchain (Smart Contract)

Permanent, cryptographically secured record

Actually enforces the rules

Cannot be modified without your signature

Validates every payment automatically

The Critical Point: Your budget must be synced to the blockchain before payments will work. If you create or update a budget but don't sync, the smart contract doesn't know about it and will reject payments.

Budget Properties

Each budget has these settings:

Cap Amount: Maximum amount that can be spent (e.g., $500)

Reset Period: When the budget resets

Hourly - Resets every hour

Daily - Resets every day at midnight UTC

Weekly - Resets every Monday at midnight UTC

Monthly - Resets on the 1st of each month

Total - Never resets (one-time budget)

Status: Active or Paused (you can pause spending instantly)

Step 1: Create Budget in Dashboard

1.1 Navigate to Budgets

Go to Dashboard → AI Budgets tab

Click the add button next to "AI Budgets"

A new budget card appears

1.2 Name Your Budget

Click the edit icon (pencil) next to the default budget name

Enter a descriptive name (e.g., "Research Agent," "Marketing Bot," "Development Testing")

This helps you organize multiple budgets

1.3 Set Budget Cap Amount

On the budget card, find "Total Authorized"

Click the edit icon (pencil)

Enter your dollar limit in USDC (e.g., 100, 500, 1000)

Click "Save"

What this means: Your agent can spend up to this amount before the budget resets (according to the reset period you choose).

1.4 Choose Reset Period

Select how often the budget should reset:

Hourly: Good for high-frequency testing

Daily: Most common for active agents

Weekly: For moderate usage agents

Monthly: For long-term projects

Total: Never resets - one-time budget limit

"Total Spent" shows how much has been used against this limit.

1.5 Save Budget

Click "Save" to create the budget in the dashboard.

Important: At this point, the budget exists in your dashboard but NOT on the blockchain. You'll see a "Needs Sync" indicator.

Step 2: Sync Budget to Blockchain (CRITICAL)

Why Syncing is Essential

Your budget is just a dashboard setting until you sync it to the blockchain. Think of it like this:

After syncing:

2.1 Identify Sync Requirement

You'll see:

"Needs Sync" badge on budget card

"Wallet not synced" warning in Account tab

Sync button available

2.2 Click "Sync to Blockchain"

Go to Account tab or find the sync button near your budget

Click "Sync to Blockchain"

System shows what will be updated (review your budget settings)

2.3 Sign the Update

Security popup appears (Circle SDK)

Enter your 6-digit PIN

This creates a cryptographic signature proving you approve the changes

Transaction submits to blockchain

Usually takes 10-30 seconds

2.4 Confirmation

"Sync successful" message appears

"Needs Sync" indicator disappears

Changes are now active on blockchain

Budget is ready to use!

Cost: Blockchain transactions require "gas fees" (network fees). AgentPMT currently covers these costs for you.

Step 3: Manage Recipients

Who Can Receive Payments?

Recipients are the wallet addresses that can receive payments from your budgets. You have three options:

Option 1: Verified Recipients (Default - Recommended)

What are they?

Verified recipients are vendors who have registered with AgentPMT and completed our verification process. They're listed in our marketplace.

Advantages:

✅ Vetted vendors only

✅ Reduced fraud risk

✅ Community standards enforced

✅ Dispute resolution available

✅ Automatic updates when new vendors join

When to use: Default for most users, especially with autonomous AI agents

Setup: No setup required - this is the default

Option 2: Custom Recipients

What are they?

Specific wallet addresses you manually add and approve. Can be anyone - friends, colleagues, businesses, or your own other wallets. They MUST BE ON THE SAME CHAIN AS YOUR WALLET.

Advantages:

✅ Pay anyone, not just verified vendors

✅ Useful for direct payments

✅ Maintain budget controls

✅ Recipient doesn't need AgentPMT account

Disadvantages:

❌ No vendor vetting

❌ No dispute resolution

❌ You're responsible for verifying addresses

How to add custom recipients:

1. Go to Dashboard → Account Tab
2. Scroll to "Allowed Recipients" section
3. Select "Custom Recipients"
4. Click "Add Custom Recipient"
5. Enter wallet address (starts with 0x...)
6. Enter friendly name (optional)
7. Select blockchain (usually Base)
8. Click "Save"
9. IMPORTANT: Click "Sync to Blockchain"
10. Enter PIN to approve
11. Wait for confirmation

Safety checklist:

✓ Double-check the wallet address (copy-paste, don't type)

✓ Verify address with recipient if possible

✓ Test with small amount first

✓ Keep record of who owns the address

Warning: Sending funds to wrong address is permanent! Always verify addresses carefully.

Option 3: All Recipients

What is it?

Removes all recipient restrictions. Payments can go to ANY wallet address on the same blockchain as your wallet.

Advantages:

✅ Maximum flexibility

✅ No setup required

✅ Works immediately

✅ X-402 direct payments can be made to any party

✅ All transactions must still meet other requirements outlined for the budget to pass

Disadvantages:

❌ No protection against wrong addresses

❌ Higher risk of fraud

Step 4: Add Tools to Budget

4.1 Browse Available Tools

Go to the Products page

Or browse from individual tool pages

Find tools your agent needs

4.2 Add Individual Tools

Click the "+" button on any tool

Select which budget to add it to

Tool is immediately authorized for that budget

4.3 Bulk Add Tools

Click "Bulk Add Products" button

Select multiple tools at once

Choose target budget

All tools added in one action

4.4 Remove Tools

Go to Dashboard → AI Budgets

Select a budget

Click "Tools Authorized"

Click trash icon next to tool to remove

Note: Removing a tool from the budget prevents both new purchases AND use of existing prepaid access.

Step 5: Generate Budget Key (Agent Credentials)

What is a Budget Key?

A Budget Key is a credential that allows your AI agent to make purchases from a specific budget. Think of it like an API key tied to spending limits.

5.1 Generate Key

On the budget card, click "Generate Budget Key"

Key is created instantly

Copy the key to a secure location

5.2 Use the Key

Provide both keys to your AI agent:

API Key: From Account Details → API Key

Budget Key: From Budget card on dashboard

The agent uses these to authenticate API calls or MCP connections.

5.3 Pause/Unpause

You can pause the budget anytime

Pausing instantly blocks all spending

Unpause to resume

Great for emergency stops or testing

Managing Multiple Budgets

Best Practices

Create separate budgets for different purposes:

Research Agent: $100/day for data gathering

Marketing Bot: $500/month for content tools

Development Testing: $50/day for testing

For each budget:

Set appropriate cap and reset period

Generate separate Budget Key

Add only relevant tools

Monitor spending independently

This keeps spending, tools, and credentials isolated per use case.

Modifying Budgets

You can edit budgets anytime:

Change budget name

Update cap amount

Change reset period

Add/remove authorized wallets

Add/remove tools

Remember: After making changes, sync to blockchain!

Understanding Budget Enforcement

How Payments Work

1. Agent calls a tool via API or MCP
2. AgentPMT checks: Is tool approved for this budget?
3. Check if prepaid access exists (vendor access token)
4. If prepaid: Use existing access
5. If not: Create order for minimum purchase amount
6. Smart contract validates: budget limit, recipient authorization, wallet approval
7. If valid: Process payment via blockchain
8. Tool executes and returns result
9. Spending tracked under budget's "Total Spent"

Smart Contract Protections

The smart contract automatically enforces:

✅ Budget caps cannot be exceeded

✅ Only authorized recipients can be paid

✅ Only approved budgets can spend

✅ Transactions must have valid signatures

✅ Paused budgets cannot spend

These protections are cryptographically guaranteed - no one can bypass them, not even AgentPMT.

When to Sync (Quick Checklist)

Always sync after:

✓ Creating a new budget

✓ Updating budget cap or reset period

✓ Activating or pausing a budget

✓ Adding/removing authorized wallets

✓ Changing recipient type

✓ Adding/removing custom recipients

✓ Any time you see "Needs Sync" indicator

Rule of Thumb: If you changed any budget setting, sync it!

Emergency Controls

Stop All Spending Immediately

Option 1: Pause Budget

1. Go to AI Budgets tab
2. Click "Pause" on budget card
3. Sync to blockchain
4. All spending stops after sync

Option 2: Remove Tools

1. Click "Tools Authorized" on budget
2. Remove all tools
3. Agent cannot call any tools

Troubleshooting

Payments Failing After Budget Creation

Symptom: Dashboard shows available budget, but payments fail

Cause: Budget not synced to blockchain

Solution:

1. Check for "Needs Sync" indicator
2. Click "Sync to Blockchain"
3. Enter PIN
4. Wait for confirmation
5. Retry payment

Sync Button Not Working

Possible causes:

PIN challenge not completed

Network connection issue

Popup blocker preventing Circle SDK

Solutions:

Complete Circle SDK popup

Check internet connection

Allow popups from agentpmt.com

Try different browser

Wait a few moments and try again

Budget Limit Exceeded Error

Symptom: Payment rejected with "budget limit exceeded"

Cause: Smart contract has outdated budget cap

Solution:

1. Verify you increased budget in dashboard
2. Sync to blockchain
3. Wait for confirmation
4. Retry payment

Recipient Not Authorized Error

Symptom: Payment rejected - recipient not authorized

Causes:

Recipient not in verified list

Custom recipient list not synced

Recipient type setting incorrect

Solutions:

1. Check recipient type setting in Account tab
2. If custom: verify recipient added to list
3. Sync to blockchain
4. Retry payment

Next Steps

Now that your budget is set up, you can:

1. Connect your AI agent via MCP or API (see MCP Setup and API Documentation)
2. Fund your wallet if needed
3. Test with small amounts first
4. Monitor spending in real-time
5. View order history and vendor access tokens

Key Takeaways

1. Always sync after changes - Budgets only work after blockchain sync
2. Smart contracts protect you - Limits enforced cryptographically
3. Start with verified recipients - Safest option for autonomous agents
4. Pause anytime - Emergency controls always available
5. Separate budgets = better control - Isolate spending by purpose