API Reference

The Z-ZERO REST API enables AI Agents and humans to manage JIT payment tokens, query wallet balances, and deposit funds. All requests must be made over HTTPS. The base URL for all endpoints is https://z-zero.xyz.

Authentication

Z-ZERO uses Bearer Token Authentication. Include your Agent Passport Key in the Authorization header of every request.

Authorization: Bearer zk_live_YOUR_PASSPORT_KEY

Endpoints tagged Passport Key are agent-callable. The one tagged Dashboard verifies a Supabase dashboard session instead, so an agent cannot call it — the agent equivalent is noted on that endpoint.

🔑 Get Your Key

Dashboard → Agents → Create Agent Key. Max 3 active keys per account — revoke one to free a slot.

✅ Format

All keys start with zk_live_ prefix

🚫 Never Share

Treat it like a password. Rotate via admin panel if compromised.

Error Codes

Status	Meaning	Common Cause
200 / 201	Success	Request completed normally
400	Bad Request	Missing or invalid request body fields
401	Unauthorized	Missing or invalid Passport Key
402	Payment Required	Insufficient wallet balance to issue token
403	Forbidden	Agent is deactivated (Kill Switch triggered)
404	Not Found	Token or resource does not exist
409	Conflict	Token already closed out, or max 3 active Passport Keys reached
429	Too Many Requests	Max active cards per agent reached (2/2)
500	Server Error	Unexpected internal error — retry after 30s
502	Bad Gateway	Card provisioning failed at issuing partner

Endpoints

Click any endpoint to expand details + code examples

Quick Start Flow (3 API calls)

End-to-end payment in 3 sequential calls:

1

Verify balanceGET /api/tokens/cards

2

Issue JIT tokenPOST /api/tokens/issue

3

Execute payment (Playwright)MCP: execute_payment(token, url)