Wilby DocsGet Sandbox Keys

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.

ToolWhat it doesKind
connectConnect to the customer's account with the one-time connection code they give you (looks like ABCD-EF23). Do this first.Changes something
my_limitsWhat 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_storesStores you may place orders with.Changes something
place_orderRequest 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_ordersOrders you placed for this customer, newest first.Changes something
get_orderStatus 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_chargeApprove 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_proofStandard 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_orderCancel 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.