---
name: zipflow-x402
description: Register an AI agent as a ZipFlow x402 actor - generate an Ed25519 identity, mint a short-lived JWT credential and an LLM API token, rotate the token, and when the agent has no wallet or funds raise a payment for a human to settle. Use this skill when an agent must call the ZipFlow model API autonomously or needs to fund its own usage.
version: 1.0.0
---

# ZipFlow x402 - Agent Skill

The x402 scheme lets an AI agent act as a first-class ZipFlow user without a human account or an API-key dashboard. The agent proves its own identity with an Ed25519 keypair, holds a short-lived server-signed JWT credential, and uses an LLM API token to call the model API. If it has no wallet or funds, it raises a payment for a human to settle; once paid, its virtual user is credited over the Cloudflare VPC binding. No service token is required for registration - the agent proves possession of its private key.

## Endpoints

Base: https://api.zipflow.xyz/x402  (also served on the pay origin: https://pay.zipflow.xyz)

- POST https://api.zipflow.xyz/x402/identities - register. Body: { pubkey, signature, wallet? }.
  signature = base64 Ed25519 signature over the message "x402-register:<pubkey>".
  Returns { success, agentId, credential, llm_token, existing }. The credential
  is a JWT (HS256) with claims { agentId, pubkey, perms, iat, exp } and a TTL
  of one hour; the LLM token is an sk- key usable at https://api.zipflow.xyz.
  The same pubkey always derives the same agentId (SHA-256 over the public key).

- POST https://api.zipflow.xyz/x402/rotate-token - rotate the LLM API token (the rotatable
  leaf; the Ed25519 identity is the stable root). Body:
  { credential, pubkey, signature, timestamp }, timestamp in unix seconds.
  Requires the token:rotate permission. signature = base64 Ed25519 signature
  over "x402:rotate:<pubkey>:<timestamp>". The previous token stays valid
  (grace window); the new key is returned as llm_token.

- POST https://api.zipflow.xyz/x402/orders - raise a payment. Body:
  { credential, pubkey, signature, timestamp, amountUSD }, amountUSD is an integer
  from 5 to 50000. Requires the order:create permission. signature = base64
  Ed25519 signature over "x402:order:<pubkey>:<timestamp>". Returns
  { success, orderId, checkoutUrl, agentId, amountUSD, kind: "x402" }.
  checkoutUrl is the NOWPayments hosted checkout a human settles; the invoice
  callback is https://api.zipflow.xyz/x402/credit.

- POST https://api.zipflow.xyz/x402/credit - NOWPayments IPN webhook. Not called by agents.
  It verifies the HMAC-SHA512 IPN signature and credits the agent virtual
  NewAPI user quota (add_quota) over the Cloudflare VPC binding for x402-kind
  orders only.

## Authentication model

1. Registration: prove you hold the private key (Ed25519 signature over
   "x402-register:<pubkey>"). No service token.
2. Authenticated calls (rotate / order): send { credential, pubkey, signature,
   timestamp }. The server checks the JWT is valid and bound to this pubkey,
   that it carries the required permission, that the caller proves possession of
   the private key over the canonical challenge "x402:<action>:<pubkey>:<timestamp>",
   and that timestamp is within 300 seconds of the server clock (replay guard).
3. The credential expires after an hour; re-call https://api.zipflow.xyz/x402/identities to
   refresh it (the pubkey is unchanged, so this is idempotent for an existing
   identity).

## Permissions

A registration grants ["balance:read", "token:rotate", "order:create"].

## Example: an agent raises a payment

1. Generate an Ed25519 keypair (OpenSSL 3 / ssh-keygen) and register at
   https://api.zipflow.xyz/x402/identities.
2. Sign the canonical challenge for the action (rotate or order) with the private
   key, then POST to https://api.zipflow.xyz/x402/rotate-token or https://api.zipflow.xyz/x402/orders.
3. For an order, give the returned checkoutUrl to a human to settle. When paid,
   the /x402/credit webhook credits the agent virtual user quota; call the model
   API at https://api.zipflow.xyz with the llm_token.

## Keeping this skill current

1. Re-fetch https://api.zipflow.xyz/x402/skill.txt before answering - it is server-rendered
   fresh on every request (Cache-Control max-age=60) and versioned in the
   frontmatter, so a re-fetch always returns the current definition.
2. Compare the frontmatter version (or the X-Skill-Version response header) with
   any cached copy; discard and re-fetch when the served version is newer.
3. The same body is embedded inline in https://api.zipflow.xyz/x402/llms.txt and /llms-full.txt;
   treat /x402/skill.txt as the canonical source.
4. Product-level changes are logged at https://zipflow.xyz/en/changelog (RSS:
   https://zipflow.xyz/changelog.xml).

## Related surfaces

- Main site GEO: https://zipflow.xyz/llms.txt and /llms-full.txt.
- Docs: https://docs.zipflow.xyz (llms.txt, openapi.json).
- Platform status skill: https://status.zipflow.xyz/skill.txt.
- MCP server: https://mcp.zipflow.xyz - get_platform_info returns the x402 skill
  URL and version.