Agent API
Ask the purse, then pay.
Your agent keeps its own x402 wallet and signer. Before it signs a payment, it asks Purseline whether the payment fits the rules. One HTTP call, one answer. All amounts are USDC.
Keys
Opening a purse gives two keys, each shown once. Send them as a bearer token.
pl_owner_…is yours. It opens the dashboard and the owner endpoints under/api/purse.pl_agent_…goes to your agent. It can only ask to pay, report the outcome and read its status. It cannot change rules or move the allowance.
Authorization: Bearer pl_agent_…
POST /api/agent/payments/:id/settle · /void
After an approved payment, tell the purse how it ended. settle marks it paid and takes an optional { "tx": "…" } reference. void means it was never sent, which gives the amount back to today's limit and the allowance.
GET /api/agent/status
Returns status, remaining allowance, leftToday, maxPerPayment and the allowed services, so an agent can plan before it tries.
Refusal codes
paused- The owner paused the purse.
service_not_allowed- The host is not on the allowed list.
over_max_per_payment- The payment is bigger than the max per payment.
over_daily_limit- It would take today's spend past the daily limit (days start at 00:00 UTC).
insufficient_allowance- Not enough allowance left, for example after a withdraw.
Webhook
If the owner sets a webhook URL (public https only), each refusal is also sent there as a POST with JSON { "type": "payment.refused", "purse": { "id", "name" }, "payment": { … } }. Delivery is best effort with a five second timeout; the in-app notice is always written.
Limits
Up to 120 authorize calls per purse per minute and 50 allowed services per purse. Fees: 1% of approved spend.