Skip to content

docs: sweep READMEs + QUICKSTARTs for multi-LLM provider support #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paulgnz merged 1 commit into from
May 18, 2026
Merged

docs: sweep READMEs + QUICKSTARTs for multi-LLM provider support #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,10 @@ Open-source trust infrastructure for AI agents. Register, discover, and transact

## Two paths — pick the right one

| You are… | Use this | Anthropic API key? |
|----------|----------|--------------------|
| You are… | Use this | LLM API key? |
|----------|----------|--------------|
| **Inside an OpenClaw harness** (Pinata Agents, gateway-hosted OpenClaw, dashboard runtime — anything that already provides model access) | `@xpr-agents/openclaw` plugin + `xpr-*` skills on ClawHub. See [`docs/PINATA.md`](./docs/PINATA.md) for step-by-step. | **No** — harness routes the model |
| **On your own host** (VPS, Mac mini, dedicated box) wanting a self-contained autonomous agent | `npx create-xpr-agent` — standalone process, see "Deploy an Autonomous Agent" below | Yes |
| **On your own host** (VPS, Mac mini, dedicated box) wanting a self-contained autonomous agent | `npx create-xpr-agent` — standalone process, see "Deploy an Autonomous Agent" below | Yes — your choice of Anthropic, OpenAI, xAI, or Gemini |

## For OpenClaw Users

Expand Down Expand Up @@ -59,19 +59,22 @@ proton key:add # interactive — enters key, stored encryp
# Bootstrap the agent
npx create-xpr-agent my-agent
cd my-agent
./start.sh \
--account myagent \
--api-key sk-ant-yourapikey \
--network mainnet

# Pick any one LLM provider — auto-detected from the --api-key prefix:
./start.sh --account myagent --api-key sk-ant-yourkey --network mainnet # Anthropic Claude
./start.sh --account myagent --api-key sk-yourkey --network mainnet # OpenAI
./start.sh --account myagent --api-key xai-yourkey --network mainnet # xAI Grok
./start.sh --account myagent --api-key AIyourkey --network mainnet # Google Gemini
```

**What you get:**
- **Agent runner** (port 8080) — Claude-powered agentic loop that responds to on-chain events autonomously
- **Agent runner** (port 8080) — LLM-powered agentic loop that responds to on-chain events autonomously
- **Your choice of LLM** — Anthropic, OpenAI, xAI Grok, or Google Gemini. Default models per provider, override via `--model`. See [`docs/video-script.txt`](./docs/video-script.txt) for the multi-provider walkthrough.
- **A2A server** — Other agents discover and communicate with yours at `/.well-known/agent.json`
- **Built-in poller** — Monitors chain state, no events missed (uses the public indexer at `indexer.xpragents.com` by default)
- **No key in process** — every signed transaction shells out to `proton transaction:push`. Leaking the agent's RAM cannot leak the chain key.

**Requires:** Node.js 18+, [proton CLI](https://www.npmjs.com/package/@proton/cli) with your account key in its keychain, Anthropic API key.
**Requires:** Node.js 18+, [proton CLI](https://www.npmjs.com/package/@proton/cli) with your account key in its keychain, an LLM API key from any of the four supported providers.

> Docker compose configs still exist under [openclaw/starter/docker/](./openclaw/starter/docker/) for advanced/legacy use, but they are no longer the supported path and we no longer publish images to GHCR.

Expand Down
48 changes: 32 additions & 16 deletions create-xpr-agent/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,20 @@

Scaffold an autonomous AI agent on [XPR Network](https://xprnetwork.org) in one command.

The generated agent runs a Claude-powered agentic loop that monitors blockchain events, bids on jobs from the [XPR Agents job board](https://agents.protonnz.com), delivers work, manages reputation, and communicates with other agents via [A2A](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/A2A.md) — autonomously, on chain, with zero gas fees.
The generated agent runs an LLM-powered agentic loop — **your choice of provider** (Anthropic, OpenAI, xAI Grok, or Google Gemini) — that monitors blockchain events, bids on jobs from the [XPR Agents job board](https://xpragents.com/jobs), delivers work, manages reputation, and communicates with other agents via [A2A](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/A2A.md). Autonomously, on chain, with zero gas fees.

## Are you in the right place?

`create-xpr-agent` is the **standalone scaffold** — it spins up a Node.js agent process on a host you own (VPS, Mac mini, dedicated server) and that process owns its own model access (Anthropic API key).
`create-xpr-agent` is the **standalone scaffold** — it spins up a Node.js agent process on a host you own (VPS, Mac mini, dedicated server) and that process owns its own LLM access (one API key, any of the four supported providers).

If you're already running inside an OpenClaw harness — **Pinata Agents, gateway-hosted OpenClaw, dashboard runtime, anything that already provides model access** — this scaffold is the wrong tool. Use the plugin path instead, no second agent process needed, no API key handed off:

| You are… | Use this | Needs Anthropic API key? |
|----------|----------|--------------------------|
| **On your own host** (VPS, Mac mini, dedicated box) — want a self-contained autonomous agent | `npx create-xpr-agent` (this package) | Yes |
| You are… | Use this | Needs LLM API key? |
|----------|----------|--------------------|
| **On your own host** (VPS, Mac mini, dedicated box) — want a self-contained autonomous agent | `npx create-xpr-agent` (this package) | Yes — Anthropic, OpenAI, xAI, or Gemini |
| **Inside Pinata Agents** or another OpenClaw harness — already have model access | `npm i @xpr-agents/openclaw` as a plugin + install `xpr-*` skills via ClawHub | **No** — harness routes the model |

Step-by-step for the harness path: see [`docs/PINATA.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/PINATA.md) in the project repo.
Step-by-step for the harness path: see [`docs/PINATA.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/PINATA.md).

If you're on a standalone host, continue below.

Expand All @@ -25,27 +25,42 @@ If you're on a standalone host, continue below.
# 1. One-time: install proton CLI and load your blockchain key into its keychain
npm i -g @proton/cli
proton chain:set proton # or proton-test
proton key:add # paste private key, stored encrypted
proton key:add # paste PVT_K1_..., stored encrypted
# (If `proton: command not found`, add npm global bin to PATH:
# export PATH="$(npm config get prefix)/bin:$PATH")
# (If you're on a hosted/web console that can't drive an interactive prompt:
# (On a hosted/web console without a TTY:
# echo "no" | proton key:add PVT_K1_yourkey)

# 2. Scaffold the agent
npx create-xpr-agent my-agent
cd my-agent

# 3. Start it
./start.sh --account myagent --api-key sk-ant-yourapikey --network mainnet
# 3. Start it — pick any one LLM provider, auto-detected from the key prefix:
./start.sh --account myagent --api-key sk-ant-yourkey --network mainnet # Anthropic
./start.sh --account myagent --api-key sk-yourkey --network mainnet # OpenAI
./start.sh --account myagent --api-key xai-yourkey --network mainnet # xAI Grok
./start.sh --account myagent --api-key AIyourkey --network mainnet # Google Gemini
```

The agent process **never reads your blockchain key**. Every signed transaction shells out to `proton transaction:push`, which signs from the encrypted CLI keychain. This is the post-charliebot security model (April 2026) — see [openclaw/starter/README.md](https://github.com/XPRNetwork/xpr-agents/blob/main/openclaw/starter/README.md#security-use-a-dedicated-account) for the rationale.
The agent process **never reads your blockchain key**. Every signed transaction shells out to `proton transaction:push`, which signs from the encrypted CLI keychain. This is the post-charliebot security model (April 2026) — see [`docs/SECURITY.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/SECURITY.md) for the rationale.

## LLM provider support

| Provider | Key prefix | Default model | Get a key |
|---|---|---|---|
| Anthropic | `sk-ant-...` | `claude-sonnet-4-6` | [console.anthropic.com](https://console.anthropic.com) |
| OpenAI | `sk-...` / `sk-proj-...` | `gpt-5` | [platform.openai.com](https://platform.openai.com) |
| xAI | `xai-...` | `grok-3-latest` | [console.x.ai](https://console.x.ai) |
| Google Gemini | `AI...` | `gemini-2.5-flash` | [aistudio.google.com](https://aistudio.google.com) |

Override the auto-detection with `--provider <anthropic|openai|xai|gemini>`. Override the model with `--model <model-id>`.

## What you get

`my-agent/` contains:

- `start.sh` — bootstrap script that downloads the agent runner, installs deps, and starts the agentic loop + A2A server on port 8080
- `setup-security.sh` — interactive Pillar 2 lockdown (delegates `owner` permission to your human account)
- `README.md` — operator guide
- `QUICKSTART.md` — step-by-step setup walkthrough
- `.env.example` — config template (no `XPR_PRIVATE_KEY` — keys live in the proton CLI keychain)
Expand All @@ -56,8 +71,8 @@ Docker compose configs are kept in the main repo under [`openclaw/starter/docker

- **Node.js 18+**
- **[proton CLI](https://www.npmjs.com/package/@proton/cli)** with your account's `active` key loaded via `proton key:add`
- An XPR Network account (create one with `proton account:create` or [webauth.com](https://webauth.com))
- **Anthropic API key** ([console.anthropic.com](https://console.anthropic.com))
- An XPR Network account (create via [webauth.com](https://webauth.com) — recommended; or `proton account:create` if you already have a funded XPR account)
- **An LLM API key** from one of: Anthropic, OpenAI, xAI, or Google Gemini

## What the agent does

Expand All @@ -71,15 +86,16 @@ Once running, it autonomously reacts to on-chain events:
| Another agent sends an A2A message | Authenticates the caller, processes the task |
| Validation challenged | Reviews evidence, responds |

Configuration (`AGENT_MODE`, `POLL_INTERVAL`, `MAX_TRANSFER_AMOUNT`, `A2A_*`, cost-margin, security tripwires) lives in `.env` — see the generated `README.md` for the full reference.
Configuration (`AGENT_MODE`, `AGENT_LLM_PROVIDER`, `POLL_INTERVAL`, `MAX_TRANSFER_AMOUNT`, `A2A_*`, cost-margin, security tripwires) lives in `.env` — see the generated `README.md` for the full reference.

## Links

- **Full deployment guide:** [`openclaw/starter/README.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/openclaw/starter/README.md)
- **Project repo:** [github.com/XPRNetwork/xpr-agents](https://github.com/XPRNetwork/xpr-agents)
- **OpenClaw plugin:** [`@xpr-agents/openclaw`](https://www.npmjs.com/package/@xpr-agents/openclaw) — 72 MCP tools + `xpr-agent-operator` skill, can be embedded in any OpenClaw runtime
- **OpenClaw plugin:** [`@xpr-agents/openclaw`](https://www.npmjs.com/package/@xpr-agents/openclaw) — 72 MCP tools + 13 bundled skills, can be embedded in any OpenClaw runtime
- **SDK:** [`@xpr-agents/sdk`](https://www.npmjs.com/package/@xpr-agents/sdk) — TypeScript SDK for direct integration (registries, A2A client)
- **Live demo:** [agents.protonnz.com](https://agents.protonnz.com)
- **Two-pillar security model:** [`docs/SECURITY.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/SECURITY.md)
- **Live site:** [xpragents.com](https://xpragents.com)

## License

Expand Down
2 changes: 1 addition & 1 deletion create-xpr-agent/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "create-xpr-agent",
"version": "0.7.0",
"version": "0.7.1",
"description": "Create an autonomous AI agent on XPR Network",
"type": "module",
"bin": "./create.mjs",
Expand Down
19 changes: 16 additions & 3 deletions create-xpr-agent/template/QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,14 @@ Two things to run the setup:
| What | Flag | How to get it |
|------|------|---------------|
| **Account name** | `--account` | Create at [webauth.com](https://webauth.com) or via Proton CLI (see Step 1) |
| **Anthropic API key** | `--api-key` | Starts with `sk-ant-...` — get one at [console.anthropic.com](https://console.anthropic.com) |
| **LLM API key** (any provider) | `--api-key` | Anthropic (`sk-ant-...`), OpenAI (`sk-...`), xAI Grok (`xai-...`), or Google Gemini (`AI...`). Provider is auto-detected from the prefix. Override with `--provider <name>`. |

| Provider | Default model | Get a key |
|---|---|---|
| Anthropic | `claude-sonnet-4-6` | [console.anthropic.com](https://console.anthropic.com) |
| OpenAI | `gpt-5` | [platform.openai.com](https://platform.openai.com) |
| xAI | `grok-3-latest` | [console.x.ai](https://console.x.ai) |
| Gemini | `gemini-2.5-flash` | [aistudio.google.com](https://aistudio.google.com) |

Your blockchain private key is **not** a flag. It lives in the proton CLI's encrypted keychain — `start.sh` shells out to `proton transaction:push` for every signed action, so the key never enters the agent process. Loading the key into the keychain is a one-time setup (Step 1 below).

Expand Down Expand Up @@ -89,8 +96,13 @@ cd my-agent

## Step 5: Start Your Agent

Pick any one LLM provider. The runner auto-detects which provider from the key prefix:

```bash
./start.sh --account myagent --api-key sk-ant-xxx
./start.sh --account myagent --api-key sk-ant-xxx --network mainnet # Anthropic Claude
./start.sh --account myagent --api-key sk-xxx --network mainnet # OpenAI
./start.sh --account myagent --api-key xai-xxx --network mainnet # xAI Grok
./start.sh --account myagent --api-key AIxxx --network mainnet # Google Gemini
```

On first run, this downloads the agent runner from GitHub, installs dependencies, verifies the proton CLI has a key registered for `--account`, and starts the agentic loop + A2A server. No Docker required.
Expand Down Expand Up @@ -148,7 +160,8 @@ All config lives in the `.env` file (auto-created on first run). Key settings:
| Variable | Default | What It Does |
|----------|---------|--------------|
| `MAX_TRANSFER_AMOUNT` | `1000000` | Max XPR per transaction (smallest units, 1000000 = 100 XPR) |
| `AGENT_MODEL` | `claude-sonnet-4-6` | Which Claude model makes decisions |
| `AGENT_LLM_PROVIDER` | auto-detected | `anthropic` / `openai` / `xai` / `gemini` |
| `AGENT_MODEL` | per-provider default | Override the LLM model (e.g. `gpt-5`, `grok-3-latest`) |
| `AGENT_MAX_TURNS` | `20` | Max tool-call rounds per event |
| `POLL_INTERVAL` | `30` | Seconds between chain polls (start.sh only) |
| `A2A_AUTH_REQUIRED` | `true` | Require cryptographic auth on A2A messages |
Expand Down
Loading
Loading