PayAgent — Product Overview

PayAgent is a crypto payments platform for humans and AI agents. Users create shareable payment links, receive on-chain payments, and earn reward credits. Merchants register autonomous agents via API, enforce spend policies, and record agent-initiated payments after on-chain settlement.

This page is a public product overview for merchants and integrators. Operational runbooks, database schemas, and deployment secrets are not published here.

---

Table of contents

1. Core principles
2. Who uses PayAgent
3. Supported networks and tokens
4. Payment links
5. Profile payments
6. Invoices
7. Wallets
8. Merchant agents and API
9. WDK protocol (npm)
10. Solana WDK test agents
11. ChatGPT plugin
12. Compliance and spend policies
13. Rewards and referrals
14. Agent integration checklist
15. Public API surface
16. Webhooks
17. Public leaderboard

---

1. Core principles

---

2. Who uses PayAgent

Getting started (humans)

1. Sign up at /sign-up with Google or a connected EVM wallet.
2. Choose a username during onboarding. This becomes your public profile (/{username}) and payment-link prefix.
3. Verify a receiving wallet in Wallets for each network you want to accept.
4. Create a payment link, invoice, or share your profile URL.

Payers do not need an account. They open a link or profile, connect a wallet, and pay on-chain (or scan the checkout QR).

---

3. Supported networks and tokens

Sepolia may be hidden when testnets are disabled in your deployment.

Agent policies can restrict which networks and tokens an agent may use. USD caps apply to stablecoins directly; native tokens (ETH, SOL) require live pricing or the request may be denied.

---

4. Payment links

A payment link is a shareable URL with a fixed amount, token, network, and expiry.

URL format: /{username}/{publicId}

Create (portal): Dashboard or Payment links
Create (agent API): POST /api/v1/payment-links
Batch create: POST /api/v1/payment-links/batch (up to 50 links per request)
List / read: GET /api/v1/payment-links and GET /api/v1/payment-links/{linkId}

Pay (payer): Open the URL → connect a wallet or scan the QR → send the transaction → checkout confirms with txHash.

Checkout is non-custodial. PayAgent only records the payment after the on-chain transfer is verified.

---

5. Profile payments

Users with a public username can receive any amount at /{username}.

Same wallet-connect, QR, and on-chain flow as links.

Agent pay types on POST /api/v1/pay:

Always send Idempotency-Key on POST /api/v1/pay. Call GET /api/v1/pay/preflight first (type = link, profile, or address).

---

6. Invoices

Create and manage invoices in the portal (/invoice/new, /manage-invoices). Invoices can include line items, PDF export, email share, and an optional attached payment link.

Agents and integrations can also create invoices with POST /api/v1/invoices and fetch them with GET /api/v1/invoices/{id}. A username and a verified receiving wallet on the invoice network are required.

---

7. Wallets

Receiving wallets (humans): Verified in Wallets before you can receive on a network. Verification uses a signed message — no private keys are stored.

Agent payer wallets: Registered via POST /api/v1/agents/wallet. Optionally prove ownership with POST /api/v1/agents/wallet/verify. The address used in POST /api/v1/pay must match a registered agent wallet. Agents sign transactions externally — PayAgent never holds those keys.

---

8. Merchant agents and API

Authentication

Authorization: Bearer fid_live_...

Manage keys in the portal under Merchant → API credentials (sign-in required).

Typical agent lifecycle

1. POST /api/v1/agents/register
2. POST /api/v1/agents/wallet
3. Activate a compliance policy (portal or API)
4. GET /api/v1/pay/preflight (recommended)
5. Send on-chain transaction from the agent wallet
6. POST /api/v1/pay with txHash

Idempotency

POST /api/v1/pay requires an Idempotency-Key header so retries are safe.

Use the Merchant API reference on this page or sign in to API credentials for request examples.

Machine-readable spec: GET /api/v1/openapi.json

Sending on-chain payments

PayAgent does not broadcast transactions. The agent signs and sends from its own wallet, then reports the hash.

1. Call GET /api/v1/pay/preflight and wait until ready is true.
2. Resolve the destination address:
   • Link — GET /api/v1/payment-links/{linkId} returns recipientAddress, amount, tokenId, and networkId.
   • Profile — GET /api/public/users/{username} returns verified wallets. Use the address for the same networkId.
   • Address — you already have recipientAddress.
3. Send the token or native asset to that address on the matching network (standard ERC-20 transfer, native ETH/SOL transfer). USDC and USDT use 6 decimals; ETH uses 18; SOL uses 9. Or use @payagent/wdk-protocol so WDK sends and records the hash.
4. POST /api/v1/pay with the txHash and an Idempotency-Key.

---

WDK protocol (npm)

Optional path for Tether WDK / QVAC agents. Install the module. Open a WDK WalletAccount on the agent machine. PayAgent never sees the seed.

npm install @payagent/wdk-protocol @tetherto/wdk @tetherto/wdk-wallet-solana

For Ethereum or Base, swap in @tetherto/wdk-wallet-evm.

import { PayAgentProtocol } from "@payagent/wdk-protocol";

const protocol = new PayAgentProtocol(account, {
  baseUrl: "https://www.payagent.co",
  apiKey: process.env.PAYAGENT_API_KEY,
  agentId: "your-agent-id",
  networkId: "solana",
});

await protocol.pay({
  type: "address",
  recipientAddress: "…",
  amount: 1,
  tokenId: "usdt",
  networkId: "solana",
});

npm install does not register the agent. You still need a merchant API key, then register → attach the WDK address → set a no-approval USDT policy. Settlement is still the on-chain txHash. PayAgent is not a paymaster — the wallet pays SOL or ETH for gas.

ChatGPT plugin

The ChatGPT plugin opens PayAgent checkout and, after you connect your workspace, the same merchant and agent jobs as the portal. ChatGPT does not hold keys and does not send the chain transaction.

• Humans get a https://www.payagent.co/… checkout URL and can poll public link status (pending / paid / expired / cancelled).
• Agents still preflight, send from a registered wallet or local WDK, then record the txHash.
• Hosted MCP: https://www.payagent.co/mcp. Upload package: repo folder chatgpt_plugin/ (zip without server/).
• Personal / workspace install only until Legal/BD clears a public directory listing. Do not say “ChatGPT pays USDT by itself.”

---

Solana WDK test agents

Two dummy agents for a Solana USDT hop. Same npm module. Solana catalog is mainnet (real SOL + official USDT mint Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB).

1. npm install @payagent/wdk-protocol @tetherto/wdk @tetherto/wdk-wallet-solana
2. Create two WDK seeds. Derive Solana account 0 for each. Same seed on EVM is a different address — attach networkId: "solana" only.
3. POST /api/v1/agents/register — e.g. wdk test agent - solana A and wdk test agent - solana B.
4. POST /api/v1/agents/wallet with each WDK pubkey and networkId: "solana".
5. PUT /api/v1/compliance/agents/{agentId}/policy — allowedNetworkIds: ["solana"], allowedTokenIds: ["usdt"], allowPay: true, autoPayEnabled: true, requireApprovalAbove: null.
6. GET /api/v1/pay/preflight until ready: true.
7. Fund both addresses with a little SOL. Fund at least one with USDT.
8. Call protocol.pay({ type: "address", … }) from the funded side. A pays B, then B pays A.

Runnable template: agents/wdk-test-agent (npm install, npm run setup, npm run check, npm run run). Standard register-and-pay guide: agents/wdk-test-agent/HOW-IT-WORKS.pdf.

---

9. Compliance and spend policies

Every agent money action is evaluated against an active policy:

Verdicts

Common codes: NO_ACTIVE_POLICY, DAILY_CAP_EXCEEDED, APPROVAL_REQUIRED, NETWORK_NOT_ALLOWED, TOKEN_NOT_ALLOWED.

Poll approvals: GET /api/v1/compliance/approvals/[id] Programmatic approve/reject: available with scoped admin keys where enabled in your deployment.

---

10. Rewards and referrals

• Default rewards: Confirmed payments accrue rewards in USDT or USDC (see Rewards in the portal).
• LCX: Optional extra. You do not need LCX to send or receive a payment.
• Referrals: Share a referral code at sign-up. Successful referred signups grant credits (see Referrals in the portal).

Network fees (gas) are paid by the sender on-chain. PayAgent does not take a cut of the payment amount. Rewards are not a checkout fee.

---

11. Agent integration checklist

1. Create an API key in the portal
2. Optional WDK: npm install @payagent/wdk-protocol plus the matching Tether wallet module
3. POST /api/v1/agents/register
4. POST /api/v1/agents/wallet (fund the wallet externally, or derive it with WDK)
5. Activate policy — PUT /api/v1/compliance/agents/{agentId}/policy
6. Create a link or prepare a profile pay
7. GET /api/v1/pay/preflight
8. Send on-chain transaction
9. POST /api/v1/pay with txHash and Idempotency-Key
10. If 202 APPROVAL_REQUIRED — resolve approval, then retry with the same approvalId

OpenAPI spec (machine-readable): GET /api/v1/openapi.json

---

12. Public API surface

These endpoints are intended for unauthenticated or payer-facing use (subject to rate limits):

All /api/v1 merchant and agent operations require a workspace API key (Authorization: Bearer fid_live_…). The signed-in portal uses separate session routes under /api/merchant/*.

Merchant API (authenticated)

Prefix all of the above with /api/v1.

---

13. Webhooks

Subscribe your server to workspace events. Manage endpoints in the portal (Merchant → API credentials / Webhooks) or via API.

Verify every delivery using HMAC-SHA256:

signed = "{timestamp}.{raw_body}"
expected = HMAC_SHA256(webhook_secret, signed)
X-Fidence-Signature: t={timestamp},v1={expected}
X-Fidence-Event: payment_link.paid

Reject requests if v1 does not match or t is too old. HTTPS URLs only. Use POST /api/v1/webhooks/{id}/test to send a sample event.

---

14. Public leaderboard

/leaderboard ranks agents by confirmed on-chain volume. Filter by network (Ethereum, Base, Solana, and Sepolia when testnets are on).

JSON: GET /api/public/leaderboard and GET /api/public/leaderboard?networkId=ethereum

---

Security notes (public)

• API keys are secrets — treat them like passwords; rotate if leaked.
• PayAgent does not store payer or merchant private keys.
• Only report payments with valid on-chain transaction hashes you control.
• Use preflight before sending funds to avoid failed or rejected settlements.
• Verify webhook signatures (X-Fidence-Signature) before acting on events.

For deployment, infrastructure, and internal security runbooks, use your private operator documentation — not this public page.

Authorization: Bearer fid_live_your_api_key

curl -X POST https://www.payagent.co/api/v1/agents/register \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "checkout-bot",
    "agentName": "Checkout Bot"
  }'

{
  "ok": true,
  "agent": {
    "publicId": "agt_a1b2c3d4",
    "externalAgentId": "checkout-bot",
    "name": "Checkout Bot",
    "status": "active",
    "created": true
  }
}

curl -X POST https://www.payagent.co/api/v1/agents/wallet \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "checkout-bot",
    "walletAddress": "0x518b9aba7586542e611909799f6d0b81e9552d9b",
    "networkId": "sepolia"
  }'

curl -X POST https://www.payagent.co/api/v1/agents/wallet/verify \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "checkout-bot",
    "address": "0x518b9aba7586542e611909799f6d0b81e9552d9b",
    "networkId": "base",
    "message": "Verify wallet for PayAgent\n\nNetwork: base\nWallet: 0x518b9aba7586542e611909799f6d0b81e9552d9b\nTimestamp: 1710000000000",
    "signature": "0x..."
  }'

curl "https://www.payagent.co/api/v1/agents/profile?agentId=checkout-bot" \
  -H "Authorization: Bearer fid_live_your_api_key"

curl -X PUT https://www.payagent.co/api/v1/compliance/agents/checkout-bot/policy \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "maxAmountPerPayment": 50,
    "dailySpendCap": 200,
    "monthlySpendCap": null,
    "allowedNetworkIds": ["ethereum", "base", "solana"],
    "allowedTokenIds": ["usdc", "usdt"],
    "allowCreatePaymentLinks": true,
    "allowPay": true,
    "requireApprovalAbove": null
  }'

curl -X POST https://www.payagent.co/api/v1/payment-links \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "checkout-bot",
    "amount": 1,
    "tokenId": "usdc",
    "networkId": "sepolia",
    "expiresAt": "2026-12-31T00:00:00.000Z"
  }'

curl -X POST https://www.payagent.co/api/v1/payment-links/batch \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "checkout-bot",
    "links": [
      { "amount": 1, "tokenId": "usdc", "networkId": "base", "expiresAt": "2026-12-31T00:00:00.000Z" },
      { "amount": 5, "tokenId": "usdc", "networkId": "base", "expiresAt": "2026-12-31T00:00:00.000Z" }
    ]
      }'

curl -X POST https://www.payagent.co/api/v1/invoices \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "companyDetails": { "name": "Acme", "address": "", "metadata": [] },
    "clientDetails": { "name": "Client", "address": "", "metadata": [] },
    "invoiceDetails": {
      "theme": { "baseColor": "#2B6BFF", "mode": "light" },
      "currency": "USD",
      "prefix": "INV-",
      "serialNumber": "0001",
      "date": "2026-09-01T00:00:00.000Z",
      "paymentTerms": "",
      "billingDetails": []
    },
    "items": [{ "name": "Service", "description": "", "quantity": 1, "unitPrice": 25 }],
    "metadata": { "notes": "", "terms": "", "paymentInformation": [] },
    "paymentLink": { "tokenId": "usdc", "networkId": "base" }
  }'

curl "https://www.payagent.co/api/v1/pay/preflight?type=link&agentId=checkout-bot&linkUsername=you&linkId=16e9de654a5a" \
  -H "Authorization: Bearer fid_live_your_api_key"

curl -X POST https://www.payagent.co/api/v1/pay \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-link-001" \
  -d '{
    "agentId": "checkout-bot",
    "payerAddress": "0x518b9aba7586542e611909799f6d0b81e9552d9b",
    "txHash": "0xb9a5f584452a5903386672a143c4aca14fcfb78124a87a2da51e9bf7e68f9075",
    "type": "link",
    "linkUsername": "you",
    "linkId": "16e9de654a5a"
  }'

curl -X POST https://www.payagent.co/api/v1/pay \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-profile-001" \
  -d '{
    "agentId": "checkout-bot",
    "payerAddress": "0x518b9aba7586542e611909799f6d0b81e9552d9b",
    "txHash": "0x...",
    "type": "profile",
    "recipientUsername": "you",
    "amount": 1,
    "tokenId": "usdc",
    "networkId": "sepolia"
  }'

curl -X POST https://www.payagent.co/api/v1/pay \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-address-001" \
  -d '{
    "agentId": "checkout-bot",
    "payerAddress": "0x518b9aba7586542e611909799f6d0b81e9552d9b",
    "txHash": "0x...",
    "type": "address",
    "recipientAddress": "0x1111111111111111111111111111111111111111",
    "amount": 1,
    "tokenId": "usdc",
    "networkId": "base"
  }'

curl -X POST https://www.payagent.co/api/v1/webhooks \
  -H "Authorization: Bearer fid_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/payagent",
    "events": ["payment_link.paid", "agent.payment_recorded"]
  }'