Skip to content
ZyroPayZyroPay Docs

Data flows

These are the five flows of the system, step by step, each step naming the two parts involved and the document it is sourced from. The Cardano x402 and escrow flows have their own pages: Paying with x402 and Escrow with Masumi.

Signing up with a passkey

  1. ZyroPay app → Your passkey. You create a passkey on your phone when you sign up. (ARCHITECTURE.md §2.1 step 1)
  2. ZyroPay app → Turnkey Auth Proxy. The app asks Turnkey's Auth Proxy to set up your account, with no ZyroPay server involved. (ARCHITECTURE.md §2.1 step 1)
  3. Turnkey Auth Proxy → Your Turnkey sub-org. Turnkey creates your own sub-organization and a default wallet with a Solana, an EVM and a Cardano account. (ARCHITECTURE.md §2.1 step 1)
  4. ZyroPay app → ZyroPay API. The app signs a who-am-I request with your passkey and sends it to the ZyroPay API. (ARCHITECTURE.md §2.1 step 2)
  5. ZyroPay API → Your Turnkey sub-org. The API forwards that request to Turnkey unchanged, and Turnkey confirms who you are. (ARCHITECTURE.md §2.1 step 2; API.md Sign-in)
  6. ZyroPay API → Turnkey parent org. On first login the API reads your sub-org and refuses to continue unless your passkey user is its only root. (ARCHITECTURE.md §2.1 step 3; ADR-001 D1; SECURITY.md T14)
  7. ZyroPay API → Neon Postgres. The API saves your account and wallet addresses and stores only hashes of your new session tokens. (ARCHITECTURE.md §2.1 step 4; SECURITY.md C13)
  8. ZyroPay API → ZyroPay app. The app gets a short-lived access token and a rotating refresh token, and you are in. (ARCHITECTURE.md §2.1 steps 4-5)

Connecting an AI agent

  1. AI agent → Agent sign-in (OAuth). The agent finds ZyroPay's MCP server and identifies itself with a client metadata document, or registers if it cannot. (MCP.md Server guide §2, §3)
  2. AI agent → Agent sign-in (OAuth). It starts an OAuth 2.1 sign-in with PKCE, bound to ZyroPay's single MCP resource. (MCP.md Server guide §2, §3)
  3. Agent sign-in (OAuth) → ZyroPay API. The MCP worker asks the API for a pending connection and shows you a short code like ABCD-1234. (ARCHITECTURE.md §2.4 step 2; MCP.md Server guide §3)
  4. ZyroPay app → ZyroPay API. You enter the code in the ZyroPay app and see the agent's name and where it will redirect. (ARCHITECTURE.md §2.4 step 3; MCP.md Server guide §3)
  5. ZyroPay app → ZyroPay API. You pick which wallets and networks it may use and approve the connection. (ARCHITECTURE.md §2.4 step 3)
  6. ZyroPay API → Policy engine. The new agent starts in Always Ask, with spending disabled, zero limits and no protocols. (ARCHITECTURE.md §2.4 step 3; SECURITY.md C1)
  7. Agent sign-in (OAuth) → ZyroPay API. The MCP worker sees the approval and completes the sign-in for that one agent. (ARCHITECTURE.md §2.4 step 4)
  8. Agent sign-in (OAuth) → AI agent. The agent receives a 15-minute access token and a rotating refresh token, stored only as hashes on ZyroPay's side. (MCP.md Server guide §3, §5; SECURITY.md T5)

An agent payment you approve

  1. AI agent → MCP server. The agent calls the send tool with a recipient, amount and an idempotency key. (MCP.md send; ARCHITECTURE.md §2.5)
  2. MCP server → ZyroPay API. The MCP server passes the request to the API, which checks the agent is still active. (ARCHITECTURE.md §1 rule 1; MCP.md Server guide §4)
  3. ZyroPay API → Payload hash binding. The API validates the details, builds the payment terms and fingerprints them with a hash. (ARCHITECTURE.md §2.5 step 2)
  4. ZyroPay API → Price sources. It values the payment in USD, rounding up, and treats a missing price as no valuation. (API.md Implementation notes: Validate + value; SECURITY.md C5)
  5. Policy engine → Neon Postgres. Under a row lock, the policy engine checks the agent's rules against what is already spent and reserved, and decides it needs your approval. (ARCHITECTURE.md §2.5 step 4; SECURITY.md C4)
  6. ZyroPay API → Push notifications. The request waits in PENDING_APPROVAL and you get a push notification with no amounts in it. (ARCHITECTURE.md §2.5 step 5b; ARCHITECTURE.md §2.7)
  7. ZyroPay app → Your passkey. You review the recipient and amount in the app and approve with your passkey. (ARCHITECTURE.md §2.5 step 5b; SECURITY.md T10)
  8. ZyroPay app → ZyroPay API. The API checks the hash and that your signed request is byte-for-byte the reviewed transaction. (API.md Implementation notes: Approve = sign; SECURITY.md C7)
  9. ZyroPay API → Your Turnkey sub-org. The request moves to SIGNING first, then the API forwards your passkey-signed request to Turnkey. (API.md Implementation notes: Approve = sign)
  10. Broadcasters → Chain RPC providers. The signed transaction is checked again, broadcast, and settled into the ledger when the chain confirms it. (API.md Implementation notes: Broadcast, Confirm)

An autonomous payment within limits

  1. ZyroPay app → ZyroPay API. You switch an agent to Autonomous, and the API creates a signing key and returns only its public half. (ARCHITECTURE.md §2.6 step 1; ADR-001 D6)
  2. Your passkey → Delegated signer. Your passkey creates a limited, non-root signer user in your Turnkey sub-org for that key. (ARCHITECTURE.md §2.6 step 2)
  3. Your passkey → Turnkey policy envelope. Your passkey also approves Turnkey rules that limit that signer to allowed chains, allowlisted recipients and per-transaction caps. (ARCHITECTURE.md §2.6 steps 3-4; SECURITY.md C3)
  4. AI agent → MCP server. Later the agent asks to send a native-token payment to an allowlisted recipient. (ARCHITECTURE.md §2.5; ARCHITECTURE.md §2.6)
  5. Policy engine → Neon Postgres. The policy engine checks USD and daily or monthly limits against spent plus reserved, then reserves the amount. (ARCHITECTURE.md §2.5 step 4; ADR-001 Consequence)
  6. ZyroPay API → Job queue. The approved request goes to the execute job, which re-checks that it is unexpired and the agent is still autonomous. (API.md Implementation notes: Autonomous)
  7. ZyroPay API → Delegated signer. The API signs with the delegated key, and Turnkey only allows it inside the rules you set. (API.md Implementation notes: Autonomous; ADR-001 D6)
  8. Broadcasters → Chain RPC providers. The signed bytes are checked against the reviewed bytes and broadcast. (API.md Implementation notes: Broadcast; SECURITY.md C7)
  9. Confirmation tracker → Neon Postgres. When the chain confirms, the reservation becomes a ledger entry and you get a notification. (API.md Implementation notes: Confirm; ARCHITECTURE.md §2.5 step 6)

A hijacked agent tries to drain your wallet

  1. AI agent → MCP server. A prompt-injected agent asks to send a large amount to an attacker's address. (SECURITY.md T1)
  2. MCP server → AI agent. The MCP server cannot sign anything; it can only turn the call into a request, and tool results reach the agent marked as untrusted data. (MCP.md Server guide §4, §5)
  3. Policy engine → ZyroPay API. The policy engine denies a recipient that is not allowed, or requires your approval, because agents start in Always Ask. (SECURITY.md C1; SECURITY.md C2)
  4. Policy engine → Neon Postgres. Many requests fired at once cannot add up past a limit, because each counts spent plus reserved under a row lock. (SECURITY.md T6; SECURITY.md C4)
  5. Push notifications → ZyroPay app. If approval is needed, you see the real recipient and amount in the app and can simply reject it. (SECURITY.md T10; API.md rejectApproval)
  6. ZyroPay API → Payload hash binding. If anyone swaps the recipient or amount after you approve, the hash changes and the old approval no longer applies. (ARCHITECTURE.md §1 rule 3; SECURITY.md T2)
  7. ZyroPay API → Independent decoder. A signed transaction that is not byte-for-byte the reviewed one is refused, and a mismatch after signing fails the request before broadcast. (SECURITY.md C7; API.md Implementation notes: Broadcast)
  8. Turnkey policy envelope → Delegated signer. Even in Autonomous mode with a compromised server, Turnkey's rules block payments to recipients outside the allowlist or above the per-transaction cap. (ADR-001 Consequence; SECURITY.md T3)
  9. ZyroPay app → ZyroPay API. You revoke the agent, which cancels its pending requests, releases its reservations and revokes its tokens at once. (ADR-001 D8; MCP.md Server guide §5 Revocation)

© 2026 ZyroPay. Test networks only (Cardano preprod, Solana devnet, Sepolia, Base Sepolia). Not audited. Third-party names identify the technologies ZyroPay uses; no partnership or endorsement is implied.

Cardano™ and the Cardano Logo™ are trademarks of Cardano Foundation.