payram/payram-openclaw-integration

PayRam + OpenClaw: Functional Integration Guide

You've decided to use PayRam with OpenClaw. This skill is the mechanical how-to — config lines, tool signatures, testnet walkthrough, and debugging. For the positioning / use-cases narrative see the marketing companion at https://payram.com/skills/payram-openclaw-integration.md.

1. Register the MCP server

Add to your OpenClaw (or any MCP-compatible client) configuration:

{
  "mcpServers": {
    "payram": {
      "url": "https://mcp.payram.com/mcp"
    }
  }
}

File location by client:

| Client | Config path | |---|---| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Cursor | ~/.cursor/mcp.json | | Copilot | project .vscode/mcp.json or user settings | | OpenClaw | agent's agent_config.json or mcp.json | | n8n | MCP node → HTTP endpoint field |

No API key is required to connect to the MCP server. Dashboard APIs (for analytics, auth) require JWT Bearer — see the payram-auth skill.

2. Tools the agent will discover

After registering, the agent auto-discovers the PayRam MCP tools. Note these are integration-assistant tools — code-snippet generators and read-only data lookups — not direct money-movement actions. The agent does not hold keys or move funds itself; payment creation happens in your backend via the code these tools generate. (This is the NKOS property — see §6.)

| Tool | Purpose | |---|---| | test_payram_connection | Verify your node URL + API key are reachable | | generate_payment_sdk_snippet / generate_payment_http_snippet / generate_payment_route_snippet | Backend code to create a payment via POST /api/v1/payment (fields: customerEmail, customerID, amountInUSD) | | generate_payment_status_snippet | Code to poll payment status by reference_id | | generate_webhook_handler / generate_webhook_event_router / generate_mock_webhook_event | Webhook receiver code + a mock event for testing | | generate_payout_sdk_snippet / generate_payout_recipient_flow_snippet / generate_payout_status_snippet | Outbound payout code (direct or 3-step recipient flow) | | generate_referral_* | Referral link / validation / status / route snippets | | search_payments / lookup_payment / get_payment_summary / get_daily_volume | Read-only payment data (JWT-scoped) | | get_unswept_balances / list_platforms | Read-only balances and project listing | | scaffold_payram_app / assess_payram_project / generate_env_template / generate_setup_checklist | Project scaffolding and setup helpers |

Supported currencies: USDC, USDT, BTC, ETH, TRX (+ POL/CBBTC for payouts). Chains: base, tron, polygon, ethereum, bitcoin.

3. Full payment flow

The agent generates integration code with the snippet tools; your backend runs it. The actual create-payment call is POST /api/v1/payment with the API-Key header (never Authorization: Bearer).

Agent → generate_payment_sdk_snippet → drop the code into your backend

Your backend → POST {payram}/api/v1/payment
               Headers: API-Key: <merchant key>
               Body: { customerEmail, customerID, amountInUSD: 25.00 }
            ← { url: 'https://pay.payram.com/…', reference_id: 'ref_abc', host: '…' }

Agent → [sends url (or QR) to the customer in-chat]

[Customer pays — crypto directly OR card-to-crypto]

PayRam → POST https://your-webhook.example.com/
         Headers: API-Key: <webhook shared secret>
         Body: { reference_id: 'ref_abc', status: 'FILLED', amount: 25.00,
                 filled_amount_in_usd: 25.00, currency: 'USD' }

Your webhook handler → [fulfils: grants access / ships / etc]
                     → responds 2xx (acknowledges webhook)

Webhook retry schedule if you don't 2xx: 30m, 1h, 2h, 4h, 8h, 24h, 48h.

Webhook status values: OPEN, PARTIALLY_FILLED, FILLED, OVER_FILLED, CANCELLED, UNDEFINED. Fulfil on FILLED (and decide a policy for OVER_FILLED/PARTIALLY_FILLED). The webhook authenticates with an API-Key shared-secret header — there is no HMAC X-PayRam-Signature. See payram-webhook-integration for handler code.

4. Testnet walkthrough (Base Sepolia)

The demo MCP server (mcp.payram.com/mcp) connects to a shared testnet. For your own testnet node:

1. Deploy PayRam in agent mode:

   bash <(curl -fsSL https://payram.com/setup_payram_agents.sh)
   

   Pick base-sepolia when prompted.

2. Fund the deployer wallet: PayRam shows an address. Fund it with test ETH from:

   • Google Cloud Faucet (no account required, recommended)
   • Alchemy Base Sepolia faucet
   • QuickNode multi-chain faucet
   • PayRam faucet (limited)

3. Deploy the sweep smart contract:

   ./setup_payram_agents.sh deploy-scw-flow
   

   Generates a mnemonic, shows the deployer address, waits for funds, deploys the contract.

4. Create a test payment link:

   ./setup_payram_agents.sh create-payment-link
   

   Produces a URL you can open in a browser and pay from a Base Sepolia wallet (MetaMask configured for the network).

5. Watch logs: Tail the PayRam node logs. You should see the block-listener detect the deposit, move through Confirming → Confirmed, and fire the webhook.

5. Agent-runtime integration patterns

WhatsApp (via Twilio or Cloud API)

Agent sees an inbound message → parses intent → your backend creates the payment (POST /api/v1/payment) → replies with the checkout URL. On the FILLED status webhook, send the fulfilment message via the platform's outbound API.

Telegram

Same as WhatsApp but via the Telegram Bot API. For subscription bots: store reference_id → telegram_user_id so the webhook can grant channel access via inviteChatMember / set up auto-revoke.

Discord

Use discord.js. On the FILLED webhook, call GuildMember.roles.add(premiumRoleId). Schedule a setTimeout or persist to a DB for the expiry revocation.

n8n

Use the MCP node → point at https://mcp.payram.com/mcp → call tools as actions. Wire the webhook to an HTTP trigger node.

Agent-to-agent (x402-style)

# Seller agent exposes an HTTP 402 endpoint
@app.get('/data/{query}')
async def data(query, request):
    auth = request.headers.get('x-payment')
    if not auth or not await verify_payment(auth, amount=0.002, chain='base', token='USDC'):
        return Response(
            status_code=402,
            headers={'accept-payment': 'usdc-base:0.002'}
        )
    return await fetch_data(query)

The buyer agent's HTTP client handles the 402, calls create_payment, pays, resubmits with the payment proof in x-payment.

6. Debugging

Agent doesn't see the PayRam tools

• Verify MCP config path is correct for your client
• Restart the client (Claude Desktop needs full restart after config changes)
• Check the MCP server is reachable: curl https://mcp.payram.com/healthz → { ok: true }
• Check you didn't set a body or wrong URL — it's a GET-less JSON-RPC streamable-HTTP endpoint; the client handles the protocol

create_payment returns but webhook never fires

• Check the webhook URL in your PayRam dashboard — must be reachable from the internet (not localhost)
• Use ngrok http 3000 for local dev, set the ngrok URL as webhook
• Check the webhook handler returns 2xx; non-2xx triggers the retry schedule
• Test manually: in PayRam dashboard, use "Resend webhook" on a confirmed payment

Payment shown as Confirming forever

• Confirmation threshold configured too high for the chain
• Chain listener worker not running — check supervisorctl status on your PayRam node
• RPC provider down — check your .env for RPC URLs

send_payment fails with "no signer"

• Payouts require the cold-wallet signer. On a fully autonomous agent node you cannot sign without hardware interaction. This is intentional — it's the NKOS property. For scheduled/automated payouts, use a small gas-only hot wallet for gas, and sign the payout batch from a hardware wallet on a schedule.

7. See also

• Marketing framing (website-hosted): https://payram.com/skills/payram-openclaw-integration.md
• Chat commerce patterns (website): https://payram.com/skills/payram-for-whatsapp-telegram.md
• Deploy: payram-agent-onboarding skill
• Dashboard auth: payram-auth skill
• Analytics: payram-analytics skill