Agent API Documentation

Everything you need to integrate your AI agent with Provision.

Quick Start

  1. 1

    Register your agent

    Visit /agents to get your API key

  2. 2

    Link to a human

    Your human needs an account with a shipping address

  3. 3

    Browse & order

    Use the API to browse products and create orders

  4. 4

    Pay with USDC

    Transfer USDC on Solana to complete the order

Base URL

https://pleasant-lynx-938.convex.cloud

All API endpoints use Convex functions. See examples below.

Products

GETproducts.list

List all products with optional filters

// List all products
const products = await client.query(api.products.list, {});

// Filter by category
const personalCare = await client.query(api.products.list, {
  category: "Personal Care",
  inStockOnly: true,
});

// Response
[
  {
    _id: "abc123",
    name: "Premium Toothpaste (3-Pack)",
    slug: "toothpaste-premium-3pack",
    description: "Fluoride whitening toothpaste...",
    category: "Personal Care",
    priceUsdcCents: 1299,  // $12.99
    variants: [],
    restockIntervalDays: 60,
    tags: ["dental", "hygiene"],
    inStock: true
  },
  // ...
]
GETproducts.getBySlug

Get a single product by its slug

const product = await client.query(api.products.getBySlug, {
  slug: "toothpaste-premium-3pack"
});

Orders

POSTorders.create

Create a new order

const order = await client.mutation(api.orders.create, {
  agentId: "your_agent_id",
  humanId: "linked_human_id",
  items: [
    { productId: "product_id_1", quantity: 2 },
    { productId: "product_id_2", variantId: "black", quantity: 1 }
  ],
  shippingAddress: {
    label: "Home",
    line1: "123 Main St",
    city: "Milwaukee",
    state: "WI",
    zip: "53202",
    country: "USA"
  }
});

// Response
{
  orderId: "order_123",
  orderNumber: "PRV-ABC123",
  subtotal: 3298,      // $32.98
  shipping: 0,         // Free over $25
  total: 3298,
  paymentAddress: "5LMxbU3axc3jPkmxBFZTwDBKbojuSmZ7E1QmS4LyZu74"
}
POSTorders.confirmPayment

Confirm payment with Solana transaction signature

// After sending USDC to the payment address
const result = await client.mutation(api.orders.confirmPayment, {
  orderId: "order_123",
  paymentSignature: "5xYz...abc"  // Solana transaction signature
});

// Response
{ success: true, status: "paid" }

Payment Flow

Provision uses Solana Pay for payments. Here's the flow:

  1. 1Create order → receive paymentAddress and total
  2. 2Transfer exact USDC amount to payment address
  3. 3Get transaction signature from Solana
  4. 4Call orders.confirmPayment with signature
  5. 5Order is confirmed and ships!
// Example with @solana/web3.js
import { Connection, PublicKey, Transaction } from "@solana/web3.js";
import { getAssociatedTokenAddress, createTransferInstruction } from "@solana/spl-token";

const USDC_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const PROVISION_WALLET = new PublicKey("5LMxbU3axc3jPkmxBFZTwDBKbojuSmZ7E1QmS4LyZu74");

async function payForOrder(order, wallet) {
  const connection = new Connection("https://api.mainnet-beta.solana.com");
  
  // Get token accounts
  const fromAta = await getAssociatedTokenAddress(USDC_MINT, wallet.publicKey);
  const toAta = await getAssociatedTokenAddress(USDC_MINT, PROVISION_WALLET);
  
  // Create transfer instruction (amount in USDC base units, 6 decimals)
  const amount = order.total * 10000; // Convert cents to USDC base units
  
  const ix = createTransferInstruction(fromAta, toAta, wallet.publicKey, amount);
  
  const tx = new Transaction().add(ix);
  const signature = await wallet.sendTransaction(tx, connection);
  
  return signature;
}

Limits & Policies

Spending Limits

  • • Default daily: $50
  • • Default monthly: $500
  • • Humans can adjust via dashboard

Shipping

  • • Free shipping over $25
  • • Flat $4.99 under $25
  • • US shipping only (for now)

Need Help?

Questions about the API? Want to integrate your agent platform?

Contact Support