PayRam Agent Onboarding

Looking for standard deployment with web UI? See

payram-setup

for the full dashboard installation.

PayRam Agent Onboarding enables fully automated, CLI-driven payment infrastructure for AI agents, automation pipelines, and serverless environments. No web dashboard — pure API interactions controlled via environment variables and shell commands.

When to Use Agent Mode

• AI Agent Payments: Claude, Copilot, custom MCP clients processing payments autonomously
• CI/CD Integration: Automated payment testing in deployment pipelines
• Serverless Infrastructure: Lambda/Cloud Functions triggering payment operations
• Treasury Automation: Programmatic fund management without human interaction
• Headless Commerce: Backend-only payment processing for APIs and microservices

Prerequisites

System Requirements:

• Ubuntu 22.04 or compatible Linux
• Docker (for

  PAYRAM_NODE_MODE=docker

  , default)
• 4 CPU cores, 4GB RAM minimum
• PostgreSQL database (configured during installation)

Installation Script:

curl -fsSL https://raw.githubusercontent.com/PayRam/payram-scripts/main/setup_payram_agents.sh -o setup_payram_agents.sh
chmod +x setup_payram_agents.sh

Quick Start

One-Step Interactive Flow

# Install, configure, and create first payment
./setup_payram_agents.sh

This runs the complete setup flow:

1. Network selection (testnet/mainnet)
2. Install PayRam backend via

   setup_payram.sh

3. Wait for API readiness
4. Create root user account + default project
5. Configure local frontend/backend settings
6. Blockchain setup prompt (ETH/Base/BTC-only)
7. Optional payment link generation

Fully Non-Interactive Flow

# Set environment variables
export PAYRAM_EMAIL="admin@example.com"
export PAYRAM_PASSWORD="secure-password-123"
export PAYRAM_NETWORK="testnet"
export PAYRAM_BLOCKCHAIN_SETUP="skip"  # BTC-only, no funding needed
export PAYRAM_WALLET_CHOICE="1"        # Auto-create wallet
export PAYRAM_WALLET_QUIET="1"         # Suppress prompts

# Run automated setup
./setup_payram_agents.sh

Commands Reference

Run from repository root:

./setup_payram_agents.sh [command]

Core Commands

menu

status

setup

signin

.payraminfo/headless-tokens.env

ensure-config

ensure-wallet

run

Blockchain Setup Commands

setup-eth

setup-base

deploy-scw

deploy-scw-flow

Payment & Utility Commands

create-payment-link [projectId] [email] [amountUSD]

reset-local [-y]

Environment Variables

Authentication & API

PAYRAM_API_URL

http://localhost:8080

PAYRAM_EMAIL

PAYRAM_PASSWORD

PAYRAM_CUSTOMER_ID

PAYRAM_FRONTEND_URL

http://localhost

Project & Payment Configuration

PAYRAM_PROJECT_NAME

Default Project

PAYRAM_PAYMENT_EMAIL

PAYRAM_PAYMENT_AMOUNT

10

PAYRAM_NETWORK

testnet

testnet

mainnet

PAYRAM_BLOCKCHAIN_SETUP

skip

eth

base

skip

Wallet & Node Configuration

PAYRAM_WALLET_CHOICE

1

2

3

PAYRAM_WALLET_QUIET

PAYRAM_NODE_MODE

docker

docker

host

PAYRAM_NODE_DOCKER_IMAGE

node:20-bullseye-slim

Smart Contract Wallet (SCW) Deployment

PAYRAM_ETH_RPC_URL

https://ethereum-sepolia-rpc.publicnode.com

PAYRAM_FUND_COLLECTOR

PAYRAM_SCW_NAME

Headless SCW

PAYRAM_BLOCKCHAIN_CODE

ETH

ETH

BASE

POLYGON

PAYRAM_MNEMONIC

.payraminfo/headless-wallet-secret.txt

PAYRAM_SCW_MIN_BALANCE_ETH

0.01

PAYRAM_SCW_SKIP_BALANCE_CHECK

Token Storage: Saved to

.payraminfo/headless-tokens.env

Typical Agent Workflow

1. Initial Setup (BTC-Only, No Funding Required)

export PAYRAM_EMAIL="agent@example.com"
export PAYRAM_PASSWORD="agent-secure-pass"
export PAYRAM_NETWORK="testnet"
export PAYRAM_BLOCKCHAIN_SETUP="skip"
export PAYRAM_WALLET_CHOICE="1"
export PAYRAM_WALLET_QUIET="1"

./setup_payram_agents.sh

2. Add Ethereum Payments (Requires Funding)

# Generate mnemonic and show deployer address
./setup_payram_agents.sh setup-eth

# Script will display deployer address like:
# "Send testnet ETH to: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEeB"

# Fund the address using testnet faucet:
# - https://sepoliafaucet.com
# - https://www.alchemy.com/faucets/ethereum-sepolia

# Script automatically polls for balance and deploys when funded

3. Create Payment Link

# Interactive (prompts for project, email, amount)
./setup_payram_agents.sh create-payment-link

# Non-interactive
export PAYRAM_PAYMENT_EMAIL="customer@example.com"
export PAYRAM_PAYMENT_AMOUNT="49.99"
./setup_payram_agents.sh create-payment-link

Payment URL Format:

http://localhost/payment?reference_id=ref_abc123&host=http://localhost:8080

⚠️ Critical: Use the exact URL printed. The

host

&

Smart Contract Wallet (SCW) Deployment

Deploy-SCW Flow

deploy-scw-flow

1. Generate Mnemonic: Creates BIP39 seed (saved to

   .payraminfo/headless-wallet-secret.txt

   )
2. Derive Deployer: Shows Ethereum address for funding
3. Wait for Balance: Polls RPC until balance ≥

   PAYRAM_SCW_MIN_BALANCE_ETH

4. Deploy Contract: Executes

   scripts/deploy-scw-eth.js

5. Register & Link: Adds SCW to backend and associates with project

Funding the Deployer

Testnet (Sepolia):

• Use faucets: Alchemy Sepolia Faucet or SepoliaFaucet.com
• Minimum: 0.01 ETH (configurable via

  PAYRAM_SCW_MIN_BALANCE_ETH

  )

Mainnet:

• Send real ETH to deployer address
• Recommended minimum: 0.05 ETH for reliable deployment

RPC Configuration

Default RPC Endpoints:

• ETH Testnet (Sepolia):

  https://eth-sepolia.g.alchemy.com/v2/demo

• ETH Mainnet: Requires your own Alchemy/Infura key
• Base Testnet:

  https://sepolia.base.org

• Base Mainnet:

  https://mainnet.base.org

Override with:

export PAYRAM_ETH_RPC_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"

Fund Collector (Cold Wallet)

By default, funds sweep to the deployer address. Configure a separate cold wallet:

export PAYRAM_FUND_COLLECTOR="0x1234567890abcdef1234567890abcdef12345678"
./setup_payram_agents.sh deploy-scw

Setting Up Additional Blockchains

After initial setup (which includes BTC), add EVM chains:

Ethereum Payments

./setup_payram_agents.sh setup-eth

• Sets RPC URL based on

  PAYRAM_NETWORK

  (testnet → Sepolia, mainnet → Mainnet)
• Runs full

  deploy-scw-flow

• Blockchain code:

  ETH

Base Payments

./setup_payram_agents.sh setup-base

• Sets RPC URL based on

  PAYRAM_NETWORK

  (testnet → Base Sepolia, mainnet → Base)
• Runs full

  deploy-scw-flow

• Blockchain code:

  BASE

Note: Both testnet and mainnet ETH use blockchain code

ETH

Docker Node Runtime Behavior

When

PAYRAM_NODE_MODE=docker

• JavaScript scripts run inside Docker containers

• localhost

  in

  PAYRAM_API_URL

  is mapped to

  host.docker.internal

• .payraminfo

  directory is mounted for access to tokens and mnemonic
• Requires Docker daemon running with host network access

Host Mode Alternative:

export PAYRAM_NODE_MODE="host"
./setup_payram_agents.sh deploy-scw

Agent Automation Best Practices

Non-Interactive Configuration

For fully automated agent runs, always set:

export PAYRAM_EMAIL="agent@example.com"
export PAYRAM_PASSWORD="secure-password"
export PAYRAM_CUSTOMER_ID="from-token-file"
export PAYRAM_BLOCKCHAIN_SETUP="skip"  # or "eth", "base"
export PAYRAM_WALLET_CHOICE="1"
export PAYRAM_WALLET_QUIET="1"

SCW Balance Thresholds

If RPC has delayed balance reporting, increase threshold:

export PAYRAM_SCW_MIN_BALANCE_ETH="0.02"
./setup_payram_agents.sh deploy-scw-flow

Docker Networking

Ensure Docker has access to host networking:

• Docker Desktop: Enable "Use kernel networking for UDP" in settings
• Linux: Docker daemon runs with

  --network=host

  by default

Files and Secrets Management

Token Storage:

• .payraminfo/headless-tokens.env

  — Authentication tokens (created by signin)

Wallet Secrets:

• .payraminfo/headless-wallet-secret.txt

  — BIP39 mnemonic for SCW deployment

Scripts:

• scripts/generate-deposit-wallet.js

  — BTC HD wallet generation

• scripts/generate-deposit-wallet-eth.js

  — Ethereum xpub derivation

• scripts/deploy-scw-eth.js

  — Smart contract wallet deployment

⚠️ Security: Never commit

.payraminfo/

.gitignore

Troubleshooting

./setup_payram_agents.sh

PAYRAM_API_URL

./setup_payram_agents.sh signin

ensure-config

ensure-wallet

docker logs payram 2>&1 | tail -80

host

&

\u0026

PAYRAM_API_URL=http://host.docker.internal:8080

PAYRAM_NODE_MODE=host

Reset and Reinstall

# Wipe all data and start fresh
./setup_payram_agents.sh reset-local -y

# Re-run setup
./setup_payram_agents.sh

Integration with MCP Clients

Connect your AI agent to PayRam:

{
  "mcpServers": {
    "payram": {
      "url": "http://localhost:8080/mcp",
      "apiKey": "your-api-key-from-signin"
    }
  }
}

Agent Workflow:

1. Agent calls PayRam MCP tools for payment operations
2. PayRam processes API requests without UI interaction
3. Webhooks notify agent of payment status changes
4. Agent continues workflow based on payment outcomes

Related Skills

payram-setup

payram-payment-integration

payram-webhook-integration

payram-checkout-integration