API / HTTP

Send API calls to tools directly

Sometimes it is helpful during prompt engineering to see exactly what your agent will see when they try to use a tool. Maybe you want to incorporate a tool or data source into a hardcoded workflow you are building. Or maybe your agent just works better with API calls instead of an MCP tool connection. Whatever the reason, you can access AgentPMT in the same way that you would make any other API call.

Prerequisites:

API Key: Dashboard → Account Details → API Key → Generate.

Budget Key: Dashboard → AI Budgets → select budget → Generate AI Key.

Base URL

https://api.agentpmt.com

Authentication

In every request, always include your keys in the headers like this:

X-API-KEY: YOUR_API_KEY

X-BUDGET-KEY: YOUR_BUDGET_KEY

Note: Header names are case-insensitive, but we recommend using uppercase for consistency.

Available Endpoints

List Tools Available on Your Budget

Endpoint: GET /products/fetch

Optional URL parameters:

page=1

page_size=10 (max 100)

Product fetch requests are paginated with a max size of 100 per page.

cURL Example:

Response Example:

Response Field Definitions

x-prepaid-balance: Shows the current number of prepaid tool calls available on that tool. When "uses_remaining" reaches 0, the next call will trigger a new purchase of the minimum order size.

x-pricing: Outlines the pricing structure for the tool:

metering: "prepaid" means you buy uses in advance

price_per_unit: Cost per single use in USDC

minimum_order_size: Minimum number of uses you must purchase at once

minimum_order_price: Total cost of minimum order (minimum_order_size × price_per_unit)

pagination: Tells you if you should make another call to fetch the next page of tools

Use a Tool (Purchase/Execute)

Endpoint: POST /products/purchase

cURL Example:

Response Example:

Purchase Response Fields

purchase_result: Indicates what happened with this request:

used_existing_access_token: Used prepaid access you already own

new_order_placed: Purchased new access (minimum order)

free_tool: Tool is free, no payment required

purchase_details: If a new order was placed, contains transaction details:

Order ID

Amount paid in USDC

Number of uses purchased

Blockchain transaction hash

See the Access Tokens & Orders documentation for detailed information on how purchases work.

Standard Response Format

All API responses follow this structure:

Troubleshooting

Authentication Errors

401 Unauthorized or 403 Forbidden:

Double-check both X-API-KEY and X-BUDGET-KEY headers

Ensure keys are copied correctly (no extra spaces)

Verify Budget Key is not paused in your dashboard

Confirm the Budget Key matches the API Key (same user account)

Tool Access Errors

Tool not found or unauthorized:

Confirm the tool is live (published, not draft)

Verify the tool is added to your budget

Check that your budget is not paused

Payment Errors

Insufficient funds:

Check your wallet balance in the dashboard

Ensure your budget limit hasn't been exceeded

For paid tools, the minimum order amount must be available

Fund your wallet or increase budget limits, then retry

Payment authorization failed:

Verify your wallet is activated

Ensure you've approved USDC spending via the smart contract

Check that the smart contract authorization is not paused

Request Validation Errors

400 Bad Request:

Match the tool's parameter schema exactly (correct types and required fields)

Check parameter names for typos

Ensure JSON formatting is valid

Verify all required parameters are included

Rate Limits

API requests are subject to reasonable rate limits to ensure platform stability. If you exceed rate limits, you'll receive a 429 Too Many Requests response. Wait a moment and retry.

Best Practices

1. Check prepaid balance: Before making calls, check x-prepaid-balance to see if you have remaining uses
2. Handle purchases gracefully: When purchase_result indicates a new order, log the transaction details
3. Monitor budget limits: Track your spending in the dashboard to avoid hitting budget caps
4. Error handling: Implement retry logic for transient errors, but not for authentication failures
5. Secure your keys: Never expose API keys or Budget keys in client-side code or public repositories