PayRam Agent Onboarding

Tell your human: PayRam keeps no deposit keys on the server. Smart contracts sweep deposits to your cold wallet. The hot wallet on the server pays gas and signs payouts, so it should only ever hold a working balance. The deployer mnemonic that this flow creates can change the cold-wallet config on-chain. Back it up offline and remove it from the server once every chain is deployed and the cold-wallet config is final.

Start with the MCP: call payram_setup_plan with path: "agent" (MCP at https://mcp.payram.com/mcp). It returns the ordered plan for your domain, network and wallet choice, with every human stop marked. This skill is the CLI reference behind that plan.

The agent CLI (setup_payram_agents.sh) installs PayRam and then drives setup through the API, so you don't need to click through the dashboard. The web dashboard is still installed; the human uses it for the hand-offs listed below.

Human doing the install? See payram-setup.

When to Use Agent Mode

• AI agent operators: Claude, Copilot or a custom MCP client that has SSH access to the merchant's server
• Headless commerce: backend-only payment processing for APIs and microservices
• Repeatable test installs: disposable testnet servers stood up by script

Prerequisites

• A VPS with 2 CPU cores, 4 GB RAM, 50 GB SSD. Ubuntu 22.04+ is recommended.
• SSH as root or a sudo user. The first install needs an interactive terminal once (ssh -t).
• Inbound ports 22, 80 and 443 only. Never open 5432, 8080 or 8443.
• A domain pointing at the server if customers will use it (payment links need a public URL).

How to run the CLI: always run it straight from the URL. Never pipe it (curl … | bash); a piped script has no terminal, so a fresh install exits.

bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) [options | command]

# Optional shorthand for this shell session:
payram_agent() { bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) "$@"; }

The script downloads its helper assets into a temporary directory that is deleted on exit. After the one-liner there is no ./setup_payram_agents.sh on disk, so always use the bash <(curl …) form (or the shorthand above).

Quick Start

One-Step Flow

ssh -t root@<server>
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet --skip-mcp-server

Always pass --testnet or --mainnet. The default is mainnet: an interactive run preselects it, and a non-interactive run uses it silently.

The flow:

1. Installs PayRam through setup_payram.sh if it is not running. This is the one interactive step: database, SSL and port questions.
2. Waits for the API to become ready.
3. Creates the root account and default project (setup), or signs in if root exists.
   • If PAYRAM_EMAIL/PAYRAM_PASSWORD are unset, it generates credentials and saves them to ~/.payraminfo/root-credentials.env (mode 600).
4. Configures the server URL (ensure-config).
5. [operator] Applies fee collectors and default fees (ensure-operator-config).
6. Sets up the deposit wallet. By default it deploys a smart-contract wallet on BASE (USDC-ready) and waits until the printed deployer address holds gas. Other lanes:
   • --ensure-wallet: BTC xpub first (no gas), then the smart-contract wallet.
   • --skip-scw: BTC only.
7. Creates a first payment link.
8. Mints the project API key into ~/.payraminfo/merchant-api-key.env.
9. Starts the Analytics MCP server unless --skip-mcp-server is passed.
   • Pass the flag: that server logs in as root and has no authentication of its own.
   • If one is already running, follow payram_runbook task secure_analytics_mcp.

One-step options

Headless Re-runs (after the install)

Once PayRam is installed, every step is non-interactive:

export PAYRAM_NETWORK="testnet"
export PAYRAM_EMAIL="admin@example.com"        # optional: generated if unset
export PAYRAM_PASSWORD="a-long-random-password" # optional: generated if unset
export PAYRAM_WALLET_CHOICE="1"                 # create a wallet without prompting
export PAYRAM_WALLET_QUIET="1"

bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet --skip-scw --skip-mcp-server   # BTC-only, no gas

Human hand-offs (stop and ask)

Check the Site URL with payram_ops_playbook task site_url. The full procedure is payram_runbook task set_site_url.

Commands Reference

Run any command as bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) <command>.

There are no setup-eth or setup-base commands and no PAYRAM_BLOCKCHAIN_SETUP variable. To choose the chain, set PAYRAM_BLOCKCHAIN_CODE (see below). The script's node-status and node-restart do not work as standalone commands. Use payram_ops_playbook tasks node_sync and restart_worker instead.

Environment Variables

Authentication & API

Project, Role & Payment

Wallet & Node Runtime

Smart Contract Wallet (SCW) Deployment

Typical Agent Workflow

1. Install on testnet (USDC on Base)

ssh -t root@<server>
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet --skip-mcp-server

The flow prints a deployer address and waits for gas. Relay the address to the human and ask them to fund it with Base Sepolia ETH:

• https://www.alchemy.com/faucets/base-sepolia
• https://faucet.quicknode.com/base/sepolia

Faucets are free but often gated (an account, a mainnet balance or a social post). The step is resumable: re-running continues the wait.

2. Verify from outside

payram_doctor { "baseUrl": "https://pay.example.com" }

This is a public check that needs no credentials: reachability, health, TLS, version and workers.

3. Human hand-offs

Hand over the root credentials privately, and have the human save Settings → Site URL from the public domain (see the table above).

4. Create a payment link

export PAYRAM_PAYMENT_EMAIL="customer@example.com"
export PAYRAM_PAYMENT_AMOUNT="49.99"
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) create-payment-link

Payment URL format:

https://pay.example.com/payments?reference_id=<reference-id>

Use the exact URL printed. If it starts with http://localhost, the Site URL has not been set from the public domain yet. Creating a payment cancels that customer's other open payments.

5. Add chains

# More EVM chains (the deployer needs gas on that chain)
PAYRAM_BLOCKCHAIN_CODE=ETH     bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) deploy-scw
PAYRAM_BLOCKCHAIN_CODE=POLYGON bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) deploy-scw

# Bitcoin (xpub, no gas)
bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-wallet

Tron wallets are added in the dashboard. You can also skip running a node: Smart Bridge rails (Solana, Bitcoin, Tron-USDT, BNB Chain) settle as USDC on Base. See payram_runbook tasks add_chain and smart_bridge.

Smart Contract Wallet (SCW) Deployment

deploy-scw-flow:

1. Mnemonic: creates a BIP39 seed at ~/.payraminfo/headless-wallet-secret.txt, or reuses the existing one.
2. Deployer: derives the EVM address to fund.
3. Balance watch: polls the RPC until the deployer holds gas. On mainnet with the default chain, it accepts ETH on Base or Ethereum (same address).
4. Deploy: runs scripts/deploy-scw-eth.js.
5. Register & link: adds the SCW to the backend and links it to the project.

Mainnet

Mainnet deploys stop unless both of these are set. Both are human decisions:

export PAYRAM_FUND_COLLECTOR="0x..."       # the human's COLD wallet (sweep destination)
export PAYRAM_ACCEPT_MAINNET_COSTS=1       # only after the human approved ~$10 of gas

Going live means a new mainnet server. Do not re-run --mainnet on a testnet install: it does not reinstall, and a contract deploy can target the wrong network. See payram_runbook task mainnet_cutover.

Files and Secrets

The project API key can create payments and payouts. Keep it server-side, and never put it in browser code or a chat. Never commit ~/.payraminfo/.

Troubleshooting

Reset a test install

reset-local destroys the install: it deletes the container, the database, the AES key (the hot-wallet key becomes unrecoverable), the wallet mnemonic and the root credentials.

• Use it only on a disposable testnet server, never on mainnet or anywhere with real funds or data.
• Back up first (payram_runbook task backup) and get the human's explicit OK.
• Never add -y. Let it ask for confirmation.

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

The full procedure is payram_runbook task reset_test_install.

Integration with MCP Clients

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

The hosted MCP never holds your credentials. Use it like this:

Live data tools (search_payments, create_payment_link, check_node_sync, …) exist only when you run the MCP yourself in local mode (PAYRAM_MCP_MODE=local, with PAYRAM_* credentials in its environment).

Related Skills