Access Tokens & Orders

Overview

AgentPMT uses a prepaid access system called "vendor access tokens" to increase response speedn and minimize blockchain transaction fees, while still giving you complete control over your funds. This document explains how purchases work, how your funds are protected, and how to monitor your prepaid access.

What Are Vendor Access Tokens?

A vendor access token is a prepaid bundle of tool uses stored in your account. When you purchase access to a tool that charges per-use, you're buying a specific number of uses upfront rather than paying for each individual call.

Example:

A tool costs $0.01 per use with a minimum purchase of 100 uses.

First call: Your agent purchases 100 uses for $1.00 USDC

A vendor access token is created with 100 uses

This call consumes 1 use (99 remaining)

Next 99 calls: Use the prepaid token (no additional purchase)

Call #101: Automatically purchases another 100 uses for $1.00

Why Minimum Purchase Amounts?

While blockchain transactions are typically cheaper than credit card transactions, they still incur gas fees and processing costs. By setting a minimum purchase amount, you are able to enjoy a much lower per-use cost:

The system will round up to the nearest whole number of product calls that is closest to the minimum purchase amount, OR the vendors advertised minimum purchase amount, whichever is greater.

Credit Card Minimum Purchase Amounts

The minimum purchase amount for a credit card transaction is $5.

For example, if a tool is $0.30 per use, the transaction will process for 17 tool calls, which is $5.10.

USDC Minimum Purchase Amounts

The minimum purchase amount for a transaction paid with USDC is $1.

For example, if a tool is $0.30 per use, the transaction process for 4 tool calls, which is $1.20

How Orders Work

When your AI agent calls a tool, AgentPMT follows this secure process:

Step 1: Check for Existing Access

The system first checks if you have an active vendor access token for this tool. If you have valid prepaid access, the tool executes immediately using your existing token.

Step 2: Create Order (If No Valid Token)

If you don't have valid prepaid access, an order is created:

Calculate cost: minimum_order_size × price_per_unit

Check budget authorization: Is this tool approved on your budget?

Reserve budget atomically: Prevent overspending from concurrent requests

Verify funds availability: Does your wallet have sufficient USDC or do you have credit card payments enabled?

Step 3: Smart Contract Validation

Before any payment occurs, the smart contract validates that you authorized this transaction:

Critical Security Checks:

1. Wallet Authorization: Your wallet must have approved USDC spending.
2. Recipient Verification: The vendor wallet must be authorized in the smart contract allowlist
3. Amount Limits: The transaction amount must not exceed your approved limits
4. Budget Constraints: Your budget must have sufficient remaining balance
5. Contract Status: Your budget and contract must not be set to 'Paused'

If ANY of these checks fail, the payment is rejected and your funds remain in your wallet.

Step 4: Execute Payment

Only after all validations pass does the smart contract execute the payment:

Funds transfer from your wallet to the vendor wallet

Transaction is recorded on the blockchain (Base network)

Order status is updated to "completed"

Transaction hash is stored for verification

Step 5: Create Vendor Access Token

After successful payment, a vendor access token is created:

Step 6: Execute Tool Function

Finally, the tool executes and returns the result to your agent.

User Control & Fund Security

AgentPMT is designed so that you retain complete control of your funds at all times. Here's how:

Smart Contract Authorization

Before any payment can occur, you must explicitly authorize the Unified Payment Contract (UPC) to spend USDC from your wallet. This authorization happens once during initial setup:

1. You deploy or connect to a UPC smart contract
2. You sign a transaction approving the contract to spend USDC
3. The approval is recorded on-chain with specific limits
4. Only payments meeting contract criteria can execute

The smart contract enforces:

Maximum transaction amounts

Approved vendor wallets (allowlist)

Budget constraints per transaction

Emergency pause functionality

Budget-Level Controls

You set spending limits on each budget:

Total Authorized: Maximum lifetime spending for this budget

Period Limits: Optional daily/monthly spending caps

Tool Authorization: Explicitly add tools to each budget

Pause/Unpause: Instantly stop all spending with one click

Your agent can ONLY spend on tools you've added to their budget, and ONLY up to the limits you set.

Atomic Budget Reservation

When an order is placed, the system atomically reserves the required amount from your budget before attempting payment. This prevents race conditions where concurrent requests could exceed your budget:

If the reservation fails (insufficient budget), the payment is rejected immediately. If the payment fails after reservation, the amount is automatically rolled back.

Funds Never Leave Your Wallet Until Contract Validates

The payment flow ensures your funds are safe:

1. Order created in database (status: "processing")
2. Budget reserved (prevents double-spending)
3. Smart contract validates all criteria
4. Only then: funds transfer on blockchain
5. Order updated to "completed" with transaction hash

If validation fails at any step, the order is marked "failed" and funds remain in your wallet.

Access Token Lifecycle

Token States

active: Has remaining uses and not expired

depleted: All uses consumed (units_used ≥ units_purchased)

expired: Passed expiration date (typically 60 days)

Token Expiration

Vendor access tokens typically expire 60 days after creation to prevent indefinite accumulation. When a token expires:

Status changes from "active" to "expired"

Unused credits are forfeited

Next tool call triggers a new purchase

Token Depletion

When all purchased uses are consumed:

Status changes from "active" to "depleted"

Next tool call automatically purchases a new token

Old token remains in history for record-keeping

Viewing Your Access Tokens

You can see all your active vendor access tokens in your dashboard:

1. Go to Dashboard → AI Budgets
2. Select a budget
3. View "Active Access Tokens" section

For each token, you'll see:

Tool name

Uses purchased

Uses consumed

Uses remaining

Expiration date

Purchase date and amount

Managing Access Tokens

Using Prepaid Tools Without Budget Balance

Once you have an active vendor access token, your agent can use that tool regardless of your remaining budget balance (unless you manually remove the tool from the budget).

Example:

Budget has $5.00 remaining

You have a token with 50 uses remaining (worth $0.50)

Your agent can use all 50 prepaid uses even if budget drops to $0

New purchases require available budget balance

Removing Tool Access

To prevent your agent from using prepaid access:

1. Go to Dashboard → AI Budgets
2. Select the budget
3. Click "Tools Authorized"
4. Remove the tool from the budget

This prevents both new purchases AND use of existing prepaid access.

Pausing All Spending

To immediately stop all spending on a budget:

1. Go to Dashboard → AI Budgets
2. Click "Pause" on the budget card

This instantly blocks:

New tool purchases

Use of existing prepaid access

All API calls using that Budget Key

Order History & Tracking

Every order is recorded with complete details:

Order Record Contains:

Order ID and timestamp

Product and vendor information

Quantity purchased and total price

Budget used

Blockchain transaction hash

Payment details (payor wallet, vendor wallet, smart contract address)

Order status (processing, completed, failed)

Error details if failed

View your order history in Dashboard → Orders.

Troubleshooting

Why Did My Agent Make Another Purchase?

Your agent purchases a new access token when:

No active token exists for the tool

Existing token is depleted (all uses consumed)

Existing token has expired

Check your access tokens in the dashboard to see current status.

Order Failed with "Insufficient Funds"

Check wallet balance in Dashboard → Account Details

Check budget remaining in Dashboard → AI Budgets

Verify budget is not paused

Ensure minimum purchase amount is available

Order Failed with "Not Authorized"

Verify tool is added to your budget

Check that budget is active (not paused)

Confirm wallet has approved USDC spending (UPC authorization)

Ensure smart contract is not paused

Token Shows Remaining Uses But Tool Won't Execute

Token may be expired - check expiration date

Budget may be paused - check budget status

Tool may have been removed from budget

Check order history for error messages

Best Practices

1. Monitor token balances: Check your dashboard regularly to see which tools have remaining prepaid access
2. Fund adequately: Keep enough wallet balance to cover minimum purchases for your most-used tools
3. Set budget limits: Use budget limits as a safety net to prevent overspending
4. Review order history: Periodically review orders to understand your agent's spending patterns
5. Use pause feature: When testing or debugging, pause budgets to prevent unexpected charges
6. Remove unused tools: Remove tools from budgets when no longer needed to prevent accidental purchases

Technical Details

X402 Direct Smart Contract: Unified Payment Contract (UPC)

The X402 Direct Smart Contract is deployed on the Base network and enforces:

EIP-2612 permit-based authorization

Merkle-proof recipient verification

Per-transaction amount limits

Emergency pause functionality

Audit trail for all transactions

Database Atomicity

Budget reservations use atomic database operations to prevent race conditions in high-concurrency scenarios. The reservation either succeeds completely or fails completely - no partial updates.