Purseline

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.

Authorization: Bearer pl_agent_…

POST /api/agent/authorize

Call this when a paid tool answers with HTTP 402. The easiest body is the x402 payment requirements object your agent picked from the 402 response's accepts list:

{ "paymentRequirements": { "resource": "…", "maxAmountRequired": "…", "payTo": "…", "network": "…" } }

Or send plain fields: resource (the full URL being paid for) and amount as a USDC string with up to six decimals. amountUnits takes base units instead.

The service is the host of resource; it must be on the purse's allowed list.

Approved: 200

{ "decision": "approved", "payment": { "id": "…", "service": "…", "amount": "…", "status": "approved", … } }

Go ahead and sign the payment with your x402 client. The amount counts toward today's limit straight away.

Refused: 403

{ "decision": "refused", "code": "over_daily_limit", "reason": "…", "payment": { … } }

Do not pay. The refusal is already in the owner's log and notices.

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.