Developer API Guide

What is Liquid Agent?

Liquid Agent provides a REST API for scheduling on-chain transactions — payments and token swaps — that execute automatically at a future date and time. Build recurring payroll, subscription billing, DCA strategies, and more with a single API call.

Base URL

https://pay.liquidagent.ai

Authentication

Every request requires an API key passed via the x-api-key header.

# Example request
curl https://pay.liquidagent.ai/api/user/{userId}/scheduled-txs \
  -H "x-api-key: lq_sk_your_key_here"

Response Headers

Every response includes rate-limit and usage headers so you always know where you stand:

Get Your API Key in 30 Seconds

Step 1 — Create a Free API Key

curl -X POST https://pay.liquidagent.ai/developer/keys \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@yourcompany.com",
    "name": "My App"
  }'

Response

{
  "apiKey": "lq_sk_a1b2c3d4e5f6...",
  "keyId": "uuid-here",
  "tier": "free",
  "message": "Save this key — it cannot be shown again."
}

Step 2 — Schedule Your First Payment

curl -X POST https://pay.liquidagent.ai/api/user/your-user-id/schedule-tx \
  -H "x-api-key: lq_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "toAddress": "0xRecipientAddress...",
    "amount": "0.05",
    "token": "ETH",
    "chain": "base",
    "executeAt": "2026-04-01T09:00:00Z"
  }'

Step 3 — Check Your Scheduled Transactions

curl https://pay.liquidagent.ai/api/user/your-user-id/scheduled-txs \
  -H "x-api-key: lq_sk_your_key_here"

Core Endpoints

Schedule a Payment

Success Response

{
  "id": "a1b2c3d4-...",
  "status": "pending",
  "type": "payment",
  "toAddress": "0xRecipient...",
  "amount": "0.05",
  "token": "ETH",
  "chain": "base",
  "executeAt": "2026-04-01T09:00:00.000Z",
  "createdAt": "2026-03-12T14:30:00.000Z"
}

List Scheduled Transactions

Returns all scheduled transactions for the given user.

Cancel a Transaction

Cancels a pending scheduled transaction. Only works if the transaction hasn't been executed yet.

Error Codes

Account & Key Management

Check Your Usage

curl https://pay.liquidagent.ai/developer/usage \
  -H "x-api-key: lq_sk_your_key_here"

Response

{
  "tier": "starter",
  "month": "2026-03",
  "requestsUsed": 1247,
  "requestsIncluded": 10000,
  "overageRequests": 0,
  "overageCost": "$0.00",
  "recentRequests": [
    {
      "endpoint": "POST /api/user/abc/schedule-tx",
      "costCents": 1,
      "timestamp": "2026-03-12T14:30:00Z"
    }
  ]
}

Per-Request Pricing

Plans That Scale With You

Start free, upgrade when you're ready. Pay with crypto — ETH or USDC.

Supported Payment Chains

How Crypto Payments Work

1. Get Price — Live CoinGecko rate for your token
2. Send Crypto — Send exact amount to fee collector
3. Submit TX — POST tx hash for verification
4. Upgraded! — Tier activates immediately

Upgrade Your Tier

Step 1 — Create Payment Request

curl -X POST https://pay.liquidagent.ai/developer/payments/create \
  -H "x-api-key: lq_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetTier": "starter",
    "chain": "base",
    "token": "ETH"
  }'

Response

{
  "paymentId": "uuid-payment-id",
  "feeCollector": "0x28E7Cee93c710A89E2C6c55bAce59430079da3f2",
  "chain": "base",
  "token": "ETH",
  "amountCrypto": "0.025431000000000000",
  "amountUsd": 49,
  "priceAtPayment": 1926.12,
  "expiresAt": "2026-03-12T15:00:00Z",
  "instructions": "Send exactly 0.025431 ETH to 0x28E7..."
}

Step 2 — Send Crypto & Verify

After sending the transaction from your wallet, submit the tx hash:

curl -X POST https://pay.liquidagent.ai/developer/payments/verify \
  -H "x-api-key: lq_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "uuid-payment-id",
    "txHash": "0xabc123..."
  }'

Verification Response

{
  "success": true,
  "message": "Payment verified! Tier upgraded to starter."
}

Quick Integration

JavaScript / Node.js

const API_KEY = 'lq_sk_your_key_here';
const BASE = 'https://pay.liquidagent.ai';

// Schedule a payment for April 1st
const res = await fetch(`${BASE}/api/user/my-user-123/schedule-tx`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': API_KEY,
  },
  body: JSON.stringify({
    type: 'payment',
    toAddress: '0xRecipient...',
    amount: '0.1',
    token: 'ETH',
    chain: 'base',
    executeAt: '2026-04-01T09:00:00Z',
  }),
});

const tx = await res.json();
console.log('Scheduled:', tx.id);

Python

import requests

API_KEY = "lq_sk_your_key_here"
BASE = "https://pay.liquidagent.ai"

# Schedule a payment
resp = requests.post(
    f"{BASE}/api/user/my-user-123/schedule-tx",
    headers={"x-api-key": API_KEY},
    json={
        "type": "payment",
        "toAddress": "0xRecipient...",
        "amount": "0.1",
        "token": "ETH",
        "chain": "base",
        "executeAt": "2026-04-01T09:00:00Z",
    }
)

tx = resp.json()
print(f"Scheduled: {tx['id']}")

Recurring Payroll (Node.js Example)

// Schedule monthly payroll for 3 employees
const employees = [
  { address: '0xAlice...', amount: '2000' },
  { address: '0xBob...',   amount: '1500' },
  { address: '0xCarol...', amount: '1800' },
];

for (const emp of employees) {
  await fetch(`${BASE}/api/user/payroll/schedule-tx`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      type: 'payment',
      toAddress: emp.address,
      amount: emp.amount,
      token: 'USDC',
      chain: 'base',
      executeAt: '2026-04-01T00:00:00Z',
    }),
  });
}

We're Here to Help

Need help integrating? Have a feature request? Reach out:

• Email: support@liquidagent.ai
• API Status: GET /health