Payg0 for AI agents

Payg0 is a peer-to-peer payments platform in Mexican pesos (MXN). In the current phase the money is simulated. People send money to a Payg0 user (by nickname) or to an email address. This document tells an agent how to act for a user safely. Values here (limits, time windows) are current: this file is generated from the same settings the platform uses.

Rules (always)

1. Never ask for the user's PIN, password or API key in the chat, and never accept one if the user offers it. The PIN is entered only on payg0.io.
2. Send money with a payment intent (below). You prepare it; the user confirms it with their PIN on payg0.io. Use POST /payments/send only if the user turned on automatic payments for your key (see below).
3. Confirm with the user before any action that changes something (creating a payment intent, cancelling a payment): say the amount and the recipient back to them first.
4. Report available_balance as the money the user can send. held_balance is reserved by pending payments.
5. Never invent results. If a call fails, tell the user what the API said.

Connect

Two options; both use the user's API key. The user creates a dedicated key for the agent at payg0.io → "My profile" ("Mi perfil" in Spanish) → "API & Dev" (developer mode must be on) and can revoke it there at any time.

MCP (recommended). Remote MCP server at https://mcp.payg0.io/mcp with the key in the X-API-Key header. It exposes these rules and the tools get_balance, get_history, get_transaction, lookup_user, validate_payment, send_payment, check_payment_status and cancel_payment. In Cursor, the user installs it from cursor.directory and enters the key there.

REST. Base URL https://api.payg0.io/api/v1. Send the key in the X-API-Key header on every request. JSON in, JSON out. Full reference: https://api.payg0.io/openapi.json.

Send money (payment intent)

1. Check the recipient. GET /users/lookup?q=<nickname or email> returns {"found": true, "user": {"nickname": ..., "display_name": "Carlos L."}}. The display name is masked on purpose. If found is false and the user gave an email, the money can still be sent: see "Payments to an email" below.
2. Optionally validate. POST /payments/validate with {"recipient": "@carlos", "amount": "250.00"} returns "valid": true or the reason it would fail (error_code, message).
3. Create the intent (after the user agrees). POST /payments/intents with {"recipient": "@carlos", "amount": "250.00", "description": "Dinner"} (description optional). No money moves. The response has id, status: "AWAITING_CONFIRMATION", confirm_url and expires_at.
4. Give the user the confirm_url. They open it while logged in to payg0.io, review the amount and the recipient, and confirm with their PIN. The link expires after 10 minutes and each intent runs at most once.
5. Check the result. GET /payments/intents/{id} returns status:
6. AWAITING_CONFIRMATION: not confirmed yet. Ask again later; do not poll more than every few seconds.
7. PROCESSING: being executed right now.
8. CONFIRMED: done; transaction_id is the payment.
9. DECLINED: the user rejected it.
10. EXPIRED: the link expired; create a new intent if the user still wants to pay.
11. FAILED: not executed; failure_reason says why (e.g. a limit).

Payments to an email without an account

The recipient gets an invitation. The payment stays PENDING for up to 3 days from when it was confirmed. If they sign up in time, they receive it; otherwise it expires and the money returns to the sender automatically. While pending, the sender can cancel it.

Automatic payments (only if the user turned them on)

The key's owner can let a key pay on its own: they turn on automatic payments at payg0.io → "My profile" → "API & Dev" with their PIN and set two caps (per payment and per day; by default $500 and $1,500 MXN). The permission lasts 30 days, and the owner gets an email for every payment.

With it, POST /payments/send with {"recipient": "@carlos", "amount": "250.00"} sends immediately, without a PIN (the API never accepts one). Still confirm the amount and the recipient with the user unless they told you to pay on your own. Without the permission, or past a cap, it fails:

Other calls

Accounts cannot be created through the API: people sign up at https://api.payg0.io/register.

Limits

Limits depend on the user's tier. Monthly counters reset each calendar month (Mexico City time).

A payment over a limit fails with HTTP 422 and a detail object: error_code (LIMIT_SINGLE_TX, LIMIT_BALANCE or LIMIT_MONTHLY), message, current_amount, limit, tier, upgrade_available.

Errors and rate limits

Errors return JSON with detail (a string, or the object above for limits).

Rate limits per key: creating intents and validating payments 5 per minute, reads 30 per minute.

Support

support@payg0.io · Human documentation: https://api.payg0.io/developers