AI Agents
A customer gives an agent a permission with limits they sign themselves. The agent can pay inside it and nothing more; anything above goes back to the customer.
1. The Customer Signs a Permission
Create a link for the customer. They choose how much per order and per month, which stores and for how long, and sign it with Face ID, a fingerprint or a texted code. They get an 8-character code for their agent.
curl -X POST https://dev.usewilby.com/v1/customers/mandate-link \
-H "Authorization: Bearer $OH_KEY" \
-H "Idempotency-Key: perm-1" \
-H "content-type: application/json" \
-d '{
"customer_external_ref": "customer-1",
"payment_method_ref": "pm_test_card",
"agent_name": "My Agent",
"per_order_cents": 6000,
"monthly_cents": 20000,
"merchant_external_refs": [
"test-store"
],
"days": 30
}'
2. The Agent Connects
Over MCP: add https://dev.usewilby.com/mcp as a connector in the agent and say "connect with code …". Over the plain API:
curl -X POST https://dev.usewilby.com/agent/v1/connect -H "content-type: application/json" -d '{"code":"ABCD2345"}'
The answer has an agent key (oha_…), shown once. Codes are single-use, valid 30 minutes, and guessing is limited.
Tools
What an agent connected to https://dev.usewilby.com/mcp can do. Each tool (except connect) also takes agent_key for AI apps that don't keep the connection.
| Tool | What it does | Kind |
|---|---|---|
connect | Connect to the customer's account with the one-time connection code they give you (looks like ABCD-EF23). Do this first. | Changes something |
my_limits | What the customer allows you to do: per-order and monthly limits, stores, expiry, how much is left this month, and (if they pay by bank account) which account and the most you may approve on bank orders. | Changes something |
list_stores | Stores you may place orders with. | Changes something |
place_order | Request an order at a store at its price (or an estimate, if the final price can change). The store confirms it; if the final price is higher, it may ask for more, and you can approve extra charges only within the customer's limits. | Changes something |
list_orders | Orders you placed for this customer, newest first. | Changes something |
get_order | Status of one order, including any extra-charge requests waiting for an answer and, for bank-account orders, whether the bank payment is clearing, cleared, or came back. | Changes something |
approve_extra_charge | Approve a store's extra-charge request on an order you placed. Only works within the customer's limits; otherwise the customer must approve it themselves. | Changes something |
get_proof | Standard agent-payment proof for an order you placed (AP2-style signed mandates: the customer's permission, what you committed, and receipts). Give it to a store, bank or payment network that asks how you were authorized. | Changes something |
cancel_order | Cancel an order you placed, before the store has started on it. | Changes something |
3. The Agent Orders
curl -X POST https://dev.usewilby.com/agent/v1/orders -H "Authorization: Bearer $OHA_KEY" -H "content-type: application/json" \
-d '{"store_id":"mer_…","description":"Two large ceramic planters","amount_cents":4670}'
Inside the limits the answer says within_permission: true, with the payment rail and the signed record's link. Above a limit the answer is an error with details.needs_customer: true and the reason: the customer decides, not the agent. The customer can turn the permission off in one tap, and the agent's key stops working at once.
See Agent API for every call.