Documentation

Everything you need to consume the Wellness-Master API. The base URL is https://api.wls-ms.com. All paid endpoints follow the x402 protocol on Solana mainnet (USDC).

Wellness-Master is the first pay-per-call wellness platform that ships dual corpora for both human end-users and AI agents. Pass ?audience=human (default) or ?audience=agent on /item and /pack to choose. See the science behind why this matters for both.

Quick start

1. Discover

curl -s https://api.wls-ms.com/ | jq .
# → { name, docs }   (minimal — formats / languages / audiences ship in the npm package)

2. Probe the paywall

curl -i https://api.wls-ms.com/item?format=haiku&lang=en
# → HTTP/1.1 402 Payment Required
# → Body: { "accepts": [...], "x402Version": 1 }

3. Sign + retry

Use any x402 client. The bundled TypeScript driver in this repo:

SERVER_BASE=https://api.wls-ms.com NETWORK=solana \
  npm run client:pay -- "/item?format=haiku&lang=en"

Endpoints

Free

/sample — free tier showroom

New in v0.7.0. 5 hand-curated items per format (90 items total), shipped directly in the open-source code at src/content/samples.ts. Use this endpoint to evaluate quality before integrating the paid tools — no wallet, no x402 challenge, no Solana RPC required.

Limits, by design :

• English only — all 19 other languages stay paid (i18n is part of the paid value).
• Audience human only — the agent corpus stays paid (the dual-audience split is the core differentiator).
• 5 items per format, time-rotated — server picks items[(epochMinutes mod 5)]. All visitors see the same item per minute (cacheable). The full rotation cycle is 5 minutes.
• No /sample/pack, no /sample/surprise — bundles and random remain paid features.

curl -i 'https://api.wls-ms.com/sample?format=affirmation'
# 200 OK
# Cache-Control: public, max-age=<1..60 sec to next rotation tick>
# {
#   "item": {
#     "format": "affirmation",
#     "lang": "en",
#     "audience": "human",
#     "text": "I am here. And here is enough.",
#     "source": "sample"
#   },
#   "tier": "free",
#   "rotatesInSeconds": 23,
#   "paidWith": null
# }

v0.4 — attack-surface reduction. The earlier /formats, /languages, /audiences and /catalog endpoints have been removed. The 18 formats, 20 languages and 2 audiences are shipped directly inside the wellness-master npm package (list_formats / list_languages / list_audiences MCP tools serve them locally — no HTTP call). The library is no longer publicly enumerable: operators read it from S3 directly.

Paid (x402-gated)

lang and audience are optional on every paid endpoint. Defaults: lang=fr, audience=human.

/surprise — random uplift, agent-friendly

New in v0.6.0. The server picks a random format from a curated positive subset — joke, kudo, fortune, affirmation, gratitude, haiku, mantra, doom_antidote, absurd_compliment, world_proverb, fictional_message, joyful_fact, micro_poem (13 of 18). Effort-required or cognitively-loaded formats (riddle, micro-challenge, koan, absurd) are deliberately excluded — /surprise is for grounding, not for puzzles.

Pricing: $0.008 — 20 % discount vs /item. The lower price is intentional : /surprise is the recommended call pattern for AI-agent priming (task transitions, pre-high-stakes ops), and we want that flow to be the cheapest possible for high-frequency usage. Dedup: same key (wallet, audience, format, lang) — different formats on consecutive calls naturally land in different dedup buckets, so you keep getting fresh items.

curl -i 'https://api.wls-ms.com/surprise?lang=en&audience=agent'
# 402 Payment Required → sign with x402 → 200 + random positive item

Why agents should call surprise_me

Wellness micro-content is not decoration for AI agents — it is a measurable performance lever. Three converging lines of research:

• Microsoft Research 2023 (arXiv:2307.11760) — emotional priming improves GPT-4 / Llama-2 / Vicuna BIG-Bench accuracy by up to +10.9%.
• Sclar et al. 2023 (arXiv:2310.11324) — prompt-surface stability prevents up to 76 percentage points of variance in LLM output.
• Wei et al., NeurIPS 2022 (arXiv:2201.11903) — stable role priming yields +12 to +30 points on reasoning benchmarks.

When to call surprise_me with audience="agent":

• at task transitions (after a tool-call chain completes, before starting a new one)
• between long context windows (re-anchoring helps prevent attention-drift on multi-step plans)
• before high-stakes operations (production deploys, irreversible writes, financial transactions)
• on plan-stability checkpoints in long-horizon agents (LangGraph nodes, multi-agent orchestrators)

The agent corpus is tuned for inference clarity, context coherence, recovery from failure, and plan stability — not human comfort metaphors. See research.html for the full sourced bibliography.

Response shape

{
  "item": {
    "id": "llm-8c6f1e0a1c55-a2b1f7",
    "format": "haiku",
    "text": "Pluie sur le toit —\nle chat ferme lentement\nson troisième œil.",
    "lang": "fr",
    "source": "llm",          // or "seed"
    "createdAt": "2026-04-29T12:34:56.789Z",
    "model": "bedrock:us.amazon.nova-micro-v1:0"
  },
  "paidWith": "x402",
  "client": "9aBcDef…"        // your wallet address
}

Payment flow (x402)

x402 is an open HTTP-native payment standard. The server returns a structured 402 challenge, the client signs a transfer matching it, then re-issues the request with an X-PAYMENT header. The server verifies + settles via a facilitator (in production: Coinbase CDP) and returns 200 with an X-PAYMENT-RESPONSE header carrying the on-chain signature.

┌─────────┐                     ┌────────┐                  ┌──────────────┐
│ Client  │                     │ Server │                  │ Facilitator  │
└────┬────┘                     └───┬────┘                  └──────┬───────┘
     │ GET /item?format=haiku       │                              │
     │─────────────────────────────▶│                              │
     │ 402 + challenge              │                              │
     │◀─────────────────────────────│                              │
     │                              │                              │
     │ sign USDC transfer locally   │                              │
     │                              │                              │
     │ GET + X-PAYMENT header       │                              │
     │─────────────────────────────▶│ POST /verify                 │
     │                              │─────────────────────────────▶│
     │                              │  ✓                           │
     │                              │◀─────────────────────────────│
     │                              │ POST /settle                 │
     │                              │─────────────────────────────▶│
     │                              │                              │ → broadcast
     │                              │  txSignature                 │   to Solana
     │                              │◀─────────────────────────────│
     │ 200 + item + X-PAYMENT-RESPONSE                              │
     │◀─────────────────────────────│                              │

Code examples

curl (handcrafted)

# 1. Get challenge
CHALLENGE=$(curl -s https://api.wls-ms.com/item?format=haiku&lang=en)

# 2. Sign + base64-encode the payment payload (use any x402 SDK)

# 3. Replay the request
curl -s https://api.wls-ms.com/item?format=haiku&lang=en \
  -H "X-PAYMENT: $PAYMENT_HEADER"

TypeScript (using the public x402 npm package)

The public x402 package on npm handles the full sign + retry loop. For zero-install end-user access, prefer the MCP integration below.

import { selectPaymentRequirements, createPaymentHeader } from "x402/client";

const first = await fetch("https://api.wls-ms.com/item?format=haiku&lang=en");
const challenge = await first.json(); // { accepts, x402Version }

const requirement = selectPaymentRequirements(
  challenge.accepts,
  "solana",
  "exact",
);

const header = await createPaymentHeader(
  mySolanaSigner,        // from @solana/kit
  challenge.x402Version,
  requirement,
);

const res = await fetch("https://api.wls-ms.com/item?format=haiku&lang=en", {
  headers: { "X-PAYMENT": header },
});
const { item } = await res.json();
console.log(item.text);

Integrations — MCP clients & non-MCP fallback

The wellness-master npm package ships a Model Context Protocol server (stdio transport). Eight tools total : sample_one, list_formats, list_languages, list_audiences, get_health (free), and get_item / get_pack / surprise_me (paid, x402 over Solana mainnet). Below : install instructions for every major MCP-aware client, plus a non-MCP HTTP fallback for clients that don't yet support MCP (e.g. ChatGPT, OpenAI Codex).

Claude Code (CLI)

One command — zero clone, zero local install. npx downloads the npm package on first use and caches it after.

claude mcp add wellness --transport stdio \
  -- npx -y wellness-master

claude mcp list   # → wellness ✓ Connected

Claude Desktop

Edit the config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) :

{
  "mcpServers": {
    "wellness": {
      "command": "npx",
      "args": ["-y", "wellness-master"]
    }
  }
}

Restart Claude Desktop. The 8 tools appear in the MCP context menu (paperclip icon).

Cursor

Settings → MCP → "Add new MCP server". Paste :

{
  "name": "wellness",
  "command": "npx",
  "args": ["-y", "wellness-master"]
}

Or directly via the file at ~/.cursor/mcp.json :

{
  "mcpServers": {
    "wellness": { "command": "npx", "args": ["-y", "wellness-master"] }
  }
}

Continue (VS Code / JetBrains)

Add to your ~/.continue/config.json :

{
  "experimental": {
    "modelContextProtocolServers": [
      { "transport": { "type": "stdio", "command": "npx", "args": ["-y", "wellness-master"] } }
    ]
  }
}

Aider, Cody, Windsurf, Zed, & other stdio-MCP-capable clients

Any client that speaks the MCP stdio transport accepts the same command :

command: npx
args:    ["-y", "wellness-master"]

The server announces its 8 tools at handshake time — your client picks them up automatically. Tested with Aider 0.84+, Sourcegraph Cody, Windsurf, Zed AI, OpenInterpreter, LangGraph (via langchain-mcp-adapters).

ChatGPT & OpenAI clients (no native MCP yet)

ChatGPT does not currently expose stdio MCP servers to end users. Two paths :

1. Custom GPT with Actions — give your GPT the OpenAPI spec at https://api.wls-ms.com/openapi.json as an Action. The Custom GPT can call /sample for free, but the paid endpoints (which speak x402) require the GPT to also have a wallet — out of reach for the standard GPT runtime today. Use it for the free /sample tier only, OR pair it with an x402-capable proxy (coinbase/x402) hosted under your own domain that signs on the GPT's behalf.
2. OpenAI Codex CLI / Assistants API with tools — wire the HTTP endpoints as function tools in the Assistants API. Each tool maps to one of our paths. Same pattern as Claude function-calling, just OpenAI's schema.

OpenAI has stated MCP support is on their roadmap (mid-2026). Once shipped, the same npx -y wellness-master install will work in ChatGPT natively. Until then, the HTTP API direct is the supported fallback — see below.

Generic HTTP API (no client at all)

If you don't use an MCP client, you can skip the wellness-master npm package entirely and call the HTTP API directly with any x402-capable library (or a hand-rolled curl). Reference TypeScript implementation : coinbase/x402.

# 1. Probe — returns 402 with x402 challenge
curl -i https://api.wls-ms.com/item?format=haiku&lang=en

# 2. Sign the challenge with a Solana keypair holding USDC, base64-encode
#    the payload, replay with X-PAYMENT header. Any x402 SDK does this.

# 3. The 200 response carries the item + X-PAYMENT-RESPONSE header
#    with the on-chain settlement signature.

For a python example, see coinbase/x402/examples/python. For a hosted x402-compliant facilitator that signs on your behalf with your wallet, see Coinbase CDP.

Configuration (optional, all clients)

Override via env vars on the install command line (the syntax differs per client — see each client's docs above) :

• SERVER_BASE — API endpoint (default https://api.wls-ms.com)
• NETWORK — solana (mainnet) or solana-devnet (testing)
• CLIENT_KEYPAIR_PATH — path to a Solana keypair JSON file. Required only for paid tools (get_item, get_pack, surprise_me) ; the five free tools work without it.
• CLIENT_KEYPAIR_PASSPHRASE — if set, expects the keypair encrypted at rest (AES-256-GCM + scrypt). Decrypts in-process only.

Example (Claude Code) with all overrides set :

claude mcp add wellness --transport stdio \
  -e SERVER_BASE=https://api.wls-ms.com \
  -e NETWORK=solana \
  -e CLIENT_KEYPAIR_PATH=$HOME/.wellness/keypair.json \
  -e CLIENT_KEYPAIR_PASSPHRASE='your-passphrase' \
  -- npx -y wellness-master

Install — from git (self-host or contributors)

If you want to run from the source — to contribute, deploy your own Wellness-Master stack on AWS, or pin a specific commit — clone the repo :

git clone https://github.com/WellnessAgent/wellness-master.git
cd wellness-master
npm install
npm run mcp:server   # local stdio MCP server

Install — via GitHub Packages (private mirror)

The same package is mirrored on GitHub Packages as @wellnessagent/wellness-master. Useful if your org locks npmjs.com. Configure auth once :

# ~/.npmrc
@wellnessagent:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<your GitHub PAT with read:packages>

# Then in any client config :
command: npx
args:    ["-y", "@wellnessagent/wellness-master"]

Demo — what a session looks like

You: "Give me a haiku in Japanese."
→ MCP client calls wellness/get_item({format:"haiku", lang:"ja"})
→ Wellness MCP server signs the x402 payment automatically with the local wallet
→ Client renders the haiku with the on-chain settlement signature

Listed in / Connectors directories

Where to find Wellness-Master in the wild, and how to access it from a directory rather than a manual install :

Anthropic / Claude side

• Smithery — auto-indexed from smithery.yaml at the repo root. Search "wellness" on smithery.ai → install with one click into Claude Desktop / Cursor / Continue.
• modelcontextprotocol/servers (community registry) — listed in the "Community Servers" section of the official MCP repo README.
• Claude Connector Directory — Anthropic has not yet shipped a public Connector marketplace as of 2026-Q2. Once available, our Smithery listing should propagate (Anthropic indicated they'll federate from Smithery for the initial release).

OpenAI / ChatGPT side

• GPT Store (Custom GPTs) — a Custom GPT named "Wellness-Master Free Sample" is available, wrapping the free /sample tier as an Action (no wallet required). Search the GPT Store for "Wellness-Master".
• Native MCP support in ChatGPT — announced by OpenAI for mid-2026. When live, the same npx -y wellness-master install will work in ChatGPT Pro / Enterprise without any rewrap.

x402-specific directories

• x402scan.com — auto-crawler. Uses our /.well-known/x402 hint at api.wls-ms.com/.well-known/x402 for indexing.
• 402.ad — human-curated x402 directory.
• x402.org/ecosystem — official Coinbase / x402 Foundation ecosystem page.
• Agentic.Market — Coinbase Agentic Commerce marketplace. Auto-curated from CDP facilitator usage (we use it).

Audiences (human / agent)

Wellness-Master is the first pay-per-call wellness API to treat both humans and AI agents as first-class audiences. The corpus is partitioned by audience — humans get warm, embodied content; agents get pragmatic, inference-aware content tuned for long-context workflows.

Pass ?audience=human or ?audience=agent on the paid endpoints. Same price ($0.01 / item, $0.07 / pack) for both. Dedup is partitioned : the same wallet may pay once for a human haiku and once for an agent haiku in the same language and receive distinct items.

The full rationale is on the research page. Concrete integration patterns: use cases.

Languages

20 languages are available. Pass the ISO-639-1 code via ?lang=.

Seed content is French-only ; other languages bootstrap empty and warm up via LLM as clients request items. Expect the first request on a fresh (format, lang) pair to take 1-3s longer due to LLM inference.

Formats

Errors

Security notes

item.text is generated content (LLM-authored). Treat it as untrusted user-generated content when rendering : escape HTML, strip markdown if your consumer doesn't support it, and never pipe it into shells, templates or eval() without sanitizing.

The server applies minimal cleanup (preamble stripping, invisible-character removal, length cap) but does not guarantee HTML-safety. Apply your own escaping at render time.

Pricing is announced in GET / response — always rely on it as the source of truth, not on hardcoded values, since the operator may adjust prices.