API reference

PayNode v1 is a JSON API over HTTPS. Root: https://www.paynode.org/api. Data endpoints live under /v1/*. Action endpoints (trade, transfer) are at /trade/* and /transfer. All calls require an API key.

Quick start

# 1. Get a free key (1,000 calls/mo)
#    → https://www.paynode.org/dashboard

# 2. Verify it works
curl https://www.paynode.org/api/v1/ping \
  -H "x-api-key: pn_live_xxx"

# → { "ok": true, "plan": "free", "server_time": "2026-04-24T…" }

Authentication

Pass your key via one of:

# Option 1 - header (recommended)
-H "x-api-key: pn_live_xxx"

# Option 2 - bearer
-H "authorization: Bearer pn_live_xxx"

Every response includes x-paynode-remaining and x-paynode-reset headers so you can track usage.

Rate limits

Over-limit returns 429 with a retry-after header.

GET /v1/ping

Liveness + auth probe. Returns your plan and key prefix.

curl https://www.paynode.org/api/v1/ping -H "x-api-key: pn_live_xxx"

GET /v1/wallet/:address

SOL balance + SPL token holdings for any Solana wallet, with USD values where pricing is available.

GET /v1/wallet/4mQ…kjLp

Response:
{
  "address": "4mQ…kjLp",
  "native": { "sol": 12.4, "lamports": 12400000000 },
  "holdings": [
    { "mint": "…", "symbol": "BONK", "amount": 1230000,
      "price_usd": 0.0000237, "value_usd": 29.1, "image": "…" },
    …
  ],
  "summary": { "holding_count": 14, "tokens_value_usd": 2841.3 }
}

GET /v1/wallet/:address/transactions

Parsed, human-readable transaction history. Supports pagination and CSV/XLSX export in a single call.

# Tax export for the year
curl -o tx_2026.xlsx \
  "https://www.paynode.org/api/v1/wallet/<addr>/transactions?format=xlsx&limit=100" \
  -H "x-api-key: pn_live_xxx"

GET /v1/token/:address

Token metadata (DAS) + DEX market stats (DexScreener).

GET /v1/token/DezXAZ…263

{
  "address": "…",
  "metadata": { "name": "Bonk", "symbol": "BONK",
                 "decimals": 5, "image": "…" },
  "market": {
    "price_usd": 0.0000237,
    "market_cap": 1_837_000_000,
    "liquidity_usd": 2_184_000,
    "volume_24h": 89_000_000,
    "change_24h": 3.42,
    …
  }
}

GET /v1/token/:address/holders

Top holders with supply %. Includes aggregate top-10 / top-20 concentration ratios.

GET /v1/token/DezXAZ…263/holders?limit=20

{
  "concentration": { "top_10_pct": 12.4, "top_20_pct": 18.1 },
  "holders": [
    { "owner": "…", "amount": 123456789, "pct": 1.2 },
    …
  ]
}

POST /v1/scan

Composite rugcheck: metadata + market + holders + security score derived from liquidity, age, volume consistency, and concentration.

curl -X POST https://www.paynode.org/api/v1/scan \
  -H "x-api-key: pn_live_xxx" \
  -H "content-type: application/json" \
  -d '{"contract":"DezXAZ…263"}'

Response includes:
  security: { score, verdict: "LIKELY_SAFE"|"CAUTION"|"RISKY"|"AVOID",
              risks: [ "low liquidity", … ] }

GET /v1/quote

Jupiter v6 quote. Read-only - PayNode never signs. The quote is handed back to the user's own wallet.

GET /v1/quote?input=<mint>&output=<mint>&amount=<lamports>&slippage_bps=100

{
  "input_mint": "…", "output_mint": "…",
  "in_amount": "1000000000",
  "out_amount": "41200000",
  "price_impact_pct": "0.03",
  "route_plan": [ { "label": "Orca", … } ]
}

GET /v1/whales

Curated list of well-known profitable Solana traders. Pair with /v1/wallet/:addr/transactions to follow their moves.

POST /trade/buy

Buy a token with SOL from the user's AI wallet. The wallet must exist (create via dashboard) and be funded.

curl -X POST https://www.paynode.org/api/trade/buy \
  -H "x-api-key: pn_live_xxx" \
  -H "content-type: application/json" \
  -d '{ "token": "BONK", "amount_sol": 0.1, "slippage": 0.5 }'

// → { signature, token, amount_tokens,
//     explorer_url: "https://solscan.io/tx/…" }

POST /trade/sell

Sell a percentage (1-100) of a held token back to SOL via Jupiter.

curl -X POST https://www.paynode.org/api/trade/sell \
  -H "x-api-key: pn_live_xxx" \
  -H "content-type: application/json" \
  -d '{ "token": "BONK", "percentage": 50, "slippage": 0.5 }'

POST /transfer

Send SOL or an SPL token from the AI wallet to any Solana address.

curl -X POST https://www.paynode.org/api/transfer \
  -H "x-api-key: pn_live_xxx" \
  -H "content-type: application/json" \
  -d '{ "to": "9pR…kL3", "amount": 0.01, "token": "SOL" }'

Wallet management

Create, import, export, and delete the AI wallet. These endpoints accept phantomAddress in the body (they are user-scoped, not API-key-scoped) and are used by the dashboard UI.

Custody note: the AI wallet private key is encrypted with AES-256 and stored server-side so your agents can sign without user prompts. You can export it at any time. Never share it.

MCP - Claude Desktop, Cursor & OpenClaw

Our MCP server wraps every endpoint as a typed tool. Install once, your agent gets ten Solana tools - seven read, three write (buy, sell, transfer).

// Works with any MCP client. Same config shape.
// - Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
// - Cursor:         ~/.cursor/mcp.json
// - OpenClaw:       OpenClaw settings → MCP Servers
{
  "mcpServers": {
    "paynode": {
      "command": "npx",
      "args": ["-y", "@paynode/mcp"],
      "env": { "PAYNODE_API_KEY": "pn_live_xxx" }
    }
  }
}

ChatGPT Custom GPT

In the GPT Builder, under Actions → Import from URL, paste:

https://www.paynode.org/chatgpt-action.json

Set authentication to API Key (Custom Header Name: x-api-key), paste your key, save.

OpenAPI spec

https://www.paynode.org/openapi.json

Drop it into any OpenAPI-aware client (Postman, Insomnia, curl-generator, LangChain OpenAPIToolkit, …).