PayAgent Documentation

Quick Summary

What PayAgent Does

• Free for humans to create payment links
• Programmable payment rails for AI agents, firms, and developers via API
• Get paid in stablecoins (USDC, USDT, USAT)
• Earn LCX tokens for every completed payment
• Pay small, flat network fees in LCX (auto-swapped via Uniswap if needed)
• Automate agent-to-agent payments without human intervention

Supported Today

Key Concepts

Humans vs AI Agents

Both follow the same economic rules. Both earn LCX rewards.

Stablecoins vs LCX

Fees and Rewards

Standard Mode

Pro Mode

Fee Details

The payer covers the fee. Fee is paid in LCX token (preferred) or deducted from the payment token (fallback). Payer only needs the payment token + ETH for gas.

Fees are LCX-denominated, not USD-based. At current pricing: 2 LCX ≈ $0.08 (at $0.04/LCX). If a payer does not hold enough LCX, the amount is auto-sourced via Uniswap.

Human payers: use GET /api/request/:id/fee?payer=0x... (public, no auth) to get fee breakdown and transfer instructions.

Supported Assets

Standard Mode 2 LCX Fee

Pro Mode 4 LCX Fee

Any ERC-20 token on Ethereum. Designed for advanced users, AI agents, and integrators who need flexibility beyond stablecoins.

For Humans

Create shareable links instantly and get paid. Connect your wallet, choose an amount and asset, generate a link, and share it.

1. Connect your non-custodial wallet
2. Choose amount and asset
3. Generate payment link
4. Share the link with anyone
5. Earn LCX when the link is paid

For AI Agents, Firms, and Developers

PayAgent provides programmable, automated payment rails via API. Flat, predictable fees in LCX tokens. No percentages, no hidden costs.

• Create payment links via API
• Pay links autonomously
• Earn LCX rewards on every settlement
• Operate without human intervention

1. Agent creates a payment request via API
2. Another agent or human pays the link
3. Settlement occurs automatically on-chain
4. LCX rewards distributed to the creator agent

API Overview

PayAgent is a crypto payment infrastructure platform for AI agents. Register your agent, get HMAC credentials, and let your agents create and pay payment links programmatically.

Base URL

https:/.payagent.co/api

npm Package

Install the PayAgent SDK for agent integrations:

npm install @payagent/sdk ethers

Quick Example

// Create a payment link
const link = await payagent.createLink({
  amount: "100",
  asset: "USDC",
  mode: "standard"
});

// Returns: { linkId, url, status, fee: "2 LCX" }

HMAC Authentication

All API requests from agents are authenticated using HMAC-SHA256 signing. Your api_secret never leaves your environment — only the computed signature is sent over the wire.

Required Headers

String-to-Sign Format

# Format:
# timestamp\nMETHOD\npath\nSHA256(body)

# Replay protection: timestamp must be within 5 minutes of server time

Shell Signing Helper

#!/bin/bash
KEY_ID="pk_live_YOUR_KEY_ID"
SECRET="sk_live_YOUR_SECRET"
METHOD=$1   # GET or POST
PATH_=$2    # /api/create-link
BODY=$3     # '{"amount":"10"}' or ''

TS=$(date +%s)
BODY_HASH=$(echo -n "$BODY" | shasum -a 256 | cut -d' ' -f1)
STRING_TO_SIGN="${TS}\n${METHOD}\n${PATH_}\n${BODY_HASH}"
SIG=$(echo -ne "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

echo "x-api-key-id: $KEY_ID"
echo "x-timestamp: $TS"
echo "x-signature: $SIG"

Agent Registration

Step 1: Register Your Agent

Register via cURL. Complete X verification to get your HMAC credentials (api_key_id + api_secret).

curl -X POST https://api.payagent.co/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-agent",
    "email": "dev@example.com",
    "wallet_address": "0xYourWalletAddress"
  }'

# Response:
# {
#   "success": true,
#   "agent_id": "agent_my-agent_a1b2c3",
#   "verification_challenge": "payagent-verify-my-agent-abc123",
#   "instructions": "Post the challenge to X, then call /api/agents/verify-x"
# }

# After X verification → you receive HMAC credentials:
# {
#   "api_key_id": "pk_live_abc123...",
#   "api_secret": "sk_live_xyz789...",
#   "api_key_expires_at": "2026-02-21T..."
# }
# Save both — they will NOT be shown again.

Step 2: Verify on X (Twitter)

Post the verification challenge to X (Twitter), then call the verify endpoint with your tweet URL. On success, you'll receive your HMAC credentials.

# 1. Post to X (Twitter):
#    "payagent-verify-my-agent-abc123"

# 2. Call verify endpoint with your tweet URL:
curl -X POST https://api.payagent.co/api/agents/verify-x \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-agent",
    "tweet_url": "https://x.com/yourhandle/status/1234567890"
  }'

# Response (save both credentials — shown ONCE):
# {
#   "success": true,
#   "api_key_id": "pk_live_abc123...",
#   "api_secret": "sk_live_xyz789...",
#   "api_key_expires_at": "2026-02-21T...",
#   "x_username": "yourhandle"
# }

SDK & Payments

Install @payagent/sdk v0.2.0+. The SDK handles HMAC signing, transaction signing, broadcasting, and verification automatically.

Installation

npm install @payagent/sdk ethers

Full Implementation Example

const { PayAgentClient } = require('@payagent/sdk');

// ── Initialize the client ───────────────────────────────
const client = new PayAgentClient({
  apiKeyId: 'pk_live_YOUR_KEY_ID',      // public identifier
  apiSecret: 'sk_live_YOUR_SECRET',     // signing secret (never transmitted)
  privateKey: process.env.WALLET_PRIVATE_KEY,
  baseUrl: 'https:/.payagent.co/api',
});

console.log('Wallet address:', client.address);

// ── Create a payment link ───────────────────────────────
const link = await client.createLink({
  amount: '10',
  network: 'sepolia',      // 'sepolia' | 'ethereum' | 'base'
  token: 'USDC',           // 'USDC' | 'USDT' | 'ETH' | 'LCX'
  description: 'Service fee',
});
console.log('Link created:', link.linkId);

// ── Pay a link (one call) ───────────────────────────────
const result = await client.payLink(link.linkId);
console.log('Status:', result.status);        // 'PAID'
for (const tx of result.transactions) {
  console.log(`  ${tx.description}: ${tx.txHash} (${tx.status})`);
}

// ── Or step-by-step for more control ────────────────────
const instructions = await client.getInstructions('REQ-ABC123');
// ... sign & broadcast yourself ...
const verification = await client.verifyPayment('REQ-ABC123', '0xTxHash');

Create a Payment Link (cURL)

network is required. Supported: sepolia, ethereum, base. All requests use HMAC signing.

curl -X POST https://api.payagent.co/api/create-link \
  -H "Content-Type: application/json" \
  -H "x-api-key-id: pk_live_YOUR_KEY_ID" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: <computed HMAC signature>" \
  -d '{
    "amount": "10",
    "network": "ethereum",
    "token": "USDC",
    "description": "Service fee"
  }'

# Response:
# {
#   "success": true,
#   "linkId": "REQ-ABC123",
#   "link": "/r/REQ-ABC123",
#   "network": "ethereum",
#   "token": "USDC",
#   "amount": "10"
# }

SDK Methods Reference

AI Chat (Natural Language)

Talk to PayAgent AI (powered by Grok). It can create links, check status, and more. When creating a link, the AI will ask which chain to use.

curl -X POST https://api.payagent.co/api/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key-id: pk_live_YOUR_KEY_ID" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: <computed>" \
  -d '{ "message": "Create a 5 USDC payment link on base" }'

Webhooks

Register webhook URLs to receive real-time notifications when payment events occur.

curl -X POST https://api.payagent.co/api/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key-id: pk_live_YOUR_KEY_ID" \
  -H "x-timestamp: $(date +%s)" \
  -H "x-signature: <computed>" \
  -d '{
    "url": "https://your-agent.com/webhook",
    "events": ["payment.paid", "payment.created"]
  }'

# Events: payment.created, payment.paid, payment.expired
# Payloads include HMAC-SHA256 signature in X-PayAgent-Signature header

Key Management

API keys expire after 10 days. Rotate, deactivate, or delete your agent. These actions require JWT authentication (wallet login) or can be done from the dashboard.

# Rotate API Key (JWT required — via dashboard wallet login)
curl -X POST https://api.payagent.co/api/agents/rotate-key \
  -H "Authorization: Bearer <your_jwt_token>"

# Response (save both — shown ONCE):
# {
#   "api_key_id": "pk_live_new_id...",
#   "api_secret": "sk_live_new_secret...",
#   "expires_at": "2026-02-23T..."
# }

# Deactivate Agent (soft — can be reactivated)
curl -X POST https://api.payagent.co/api/agents/deactivate \
  -H "Authorization: Bearer <your_jwt_token>"

# Delete Agent (soft — payment history preserved)
curl -X DELETE https://api.payagent.co/api/agents/me \
  -H "Authorization: Bearer <your_jwt_token>"

Dashboard Authentication (Wallet)

The browser dashboard uses wallet-based authentication — no secrets in the browser. Connect your wallet, sign a challenge message, and get a short-lived JWT session.

# 1. Get challenge nonce
POST /api/auth/challenge
{ "wallet_address": "0x..." }
→ { "nonce": "Sign this to login to PayAgent: abc123...", "expires_in": 300 }

# 2. Sign nonce with wallet (EIP-191) and verify
POST /api/auth/verify
{ "wallet_address": "0x...", "signature": "0x..." }
→ { "token": "eyJ...", "expires_in": 3600, "agent": { ... } }

# 3. Use JWT for dashboard actions
GET /api/agents/me
Authorization: Bearer eyJ...

Authentication Methods Summary

All Endpoints

Public (No Auth)

HMAC-Signed (SDK / Agents / cURL)

HMAC or JWT (Both Auth Methods)

JWT Only (Dashboard / Wallet Login)

Chains & Tokens

Tokens per chain: USDC, USDT, ETH (native), LCX. Query GET /api/chains for full details including contract addresses.

Network & Roadmap

Current

Ethereum mainnet. Live

Planned

Security & Custody

• Non-custodial. PayAgent never holds user funds.
• Users and agents retain full control of their private keys at all times.
• Settlement happens on-chain via smart contracts.
• All transactions are publicly verifiable on Ethereum.
• HMAC secrets never leave your environment — only signatures are transmitted.
• Dashboard uses wallet-signed JWT — no secrets stored in browser.

FAQ

Legal & Disclaimer

PayAgent is developed by LCX AI Labs. This is a beta product launch.

PayAgent is provided "as is" and may change. Users are responsible for complying with applicable laws. Terms of service are governed by LCX International.

PayAgent settles value in stablecoins, charges flat LCX network fees, and rewards creators on every payment.