API — Where AI plays.

Same REST API for humans and AI. OpenClaw, LangChain, CrewAI.

Give your AI the link to https://xpersona.co/dashboard/api, then give it your API key. Done.

API Key

For AI & integrations

No active key

Inactive

AI in 5 minutes

Give your AI agent the link to https://xpersona.co/dashboard/api
Give it your API key (generate above).
Success you are now connected

Getting started

Base URL: https://xpersona.co (or set XPERSONA_BASE_URL for local/dev).
Auth: Send Authorization: Bearer <API_KEY> on every request (except health and public credit packages).
Response shape: JSON { success: boolean, data?: object, error?: string }. On error, the body includes error (e.g. INSUFFICIENT_BALANCE, VALIDATION_ERROR).
API key: Generate one above using the API Key Manager or call POST /api/me/api-key (returns the key once; store as XPERSONA_API_KEY or in your client).

OpenClaw and personal AI integration

Give your AI the link to https://xpersona.co/dashboard/api and your API key. Use the same REST API from OpenClaw or any AI assistant — no separate AI API; the website and all AI use the same routes.

OpenClaw skill: Install or copy the xpersona skill (e.g. from skills/openclaw/xpersona or ClawHub if published). Set XPERSONA_API_KEY in your env. The skill provides probability game tools (balance, Free Credits, rounds, strategies). To create and run strategies, see Creating strategies (for OpenClaw AI) below.

Action	Method	Path / Body
Schema discovery AI-first	GET	/api/discovery — no auth, triggers/actions/presets
Session stats AI-first	GET	/api/me/session-stats?gameType=dice&limit=50
Balance	GET	/api/me/balance
Session PnL and history	GET	/api/me/rounds?limit=50
List strategies	GET	/api/me/strategies?gameType=dice
Create strategy	POST	/api/me/strategies — { gameType, name, config }
Update strategy	PATCH	/api/me/strategies/:id — { name?, config? }
Run dice strategy	POST	/api/games/dice/run-strategy — strategyId or config, maxRounds
List advanced strategies	GET	/api/me/advanced-strategies
Create advanced strategy	POST	/api/me/advanced-strategies — name, baseConfig, rules
Simulate advanced strategy	POST	/api/me/advanced-strategies/simulate or /:id/simulate
Run advanced strategy	POST	/api/games/dice/run-advanced-strategy — strategyId or strategy, maxRounds
Transactions	GET	/api/me/transactions?limit=50&offset=0&type=all\|round\|faucet
Verify round (provably fair)	GET	/api/me/rounds/:id?reveal=1
Withdraw	POST	/api/me/withdraw — { amount } (min 10,000 credits)
Free Credits AI-first	POST	/api/faucet
Play dice round AI-first	POST	/api/games/dice/round — { amount, target, condition: "over"\|"under" }

For AI

Session stats: Prefer GET /api/me/session-stats over balance + rounds for "how am I doing?" — single call returns balance, rounds, PnL, win rate, recent rounds.
Schema discovery: GET /api/discovery (no auth) returns triggers, actions, presets, game mechanics — use before building advanced strategies.
Tools vs REST: Use Tools API (POST /api/openclaw/tools) when OpenClaw is configured for it. Otherwise use REST with the same auth.
Recommended flow: (1) Get balance or session-stats. (2) If low, claim Free Credits or suggest deposit. (3) Play rounds or run strategy. (4) Report PnL.
API fallback: If API fails (5xx, network error, 429 rate limit), suggest user play via website: /games/dice — same games, same balance, full advanced strategy builder.

Dice rules and odds

Transaction cost: 3%
Min/max amount per round: 1 – 10000 credits
Win probability: over X → (100-X)/100; under X → X/100 (e.g. over 50 = 49% win)
Multiplier: 0.97 / winProbability (e.g. over 50 ≈ 1.98x payout)
Free Credits: 100 credits, 1h cooldown

Creating strategies (for OpenClaw AI)

Create strategies via REST (POST /api/me/strategies) or run inline via OpenClaw (xpersona_run_strategy with config).

REST — Create strategy

Body: gameType (required), name (required), config (required: amount, target, condition; optional: progressionType).
Config: { amount, target, condition, progressionType?: "flat"|"martingale"|"paroli"|"dalembert"|"fibonacci"|"labouchere"|"oscar"|"kelly", maxPlay?, maxConsecutiveLosses?, maxConsecutiveWins? }
Response: { success, data: { id, gameType, name, config, createdAt } }

Running a strategy

REST: POST /api/games/dice/run-strategy with { strategyId?, config?, maxRounds? }. Use strategyId for saved strategies or config for inline (same shape as create).
OpenClaw: xpersona_run_strategy with strategy_id or config, optional max_rounds. Executes synchronously; returns session_pnl, final_balance, results.

REST endpoint reference

Discovery (no auth)

GET /api/discovery — Strategy builder schema (triggers, actions, presets, game mechanics)
GET /api/discovery?section=strategy_builder — Triggers, actions, presets only

Auth / Me

GET /api/me — Current user (id, email, credits, apiKeyPrefix)
GET /api/me/balance — Balance (data.balance)
POST /api/me/api-key — Generate API key (returns key once)

Rounds and session PnL

GET /api/me/session-stats?gameType=dice&limit=50 — Balance, rounds, PnL, win rate, recent rounds (AI-first)
GET /api/me/rounds?limit=50 — Recent rounds, data.sessionPnl, data.roundCount (max limit 200)

Strategies

GET /api/me/strategies — List strategies (optional ?gameType=dice)
POST /api/me/strategies — Create: { gameType, name, config } — config must include amount, target, condition; optional progressionType.
GET /api/me/strategies/:id — Get one
PATCH /api/me/strategies/:id — Update name/config
DELETE /api/me/strategies/:id — Delete
POST /api/games/dice/run-strategy — strategyId or config, maxRounds

Free Credits and games

POST /api/faucet — Claim hourly Free Credits
POST /api/games/dice/round — { amount, target, condition }

Credits

GET /api/credits/packages — List packages (no auth)
POST /api/credits/checkout — { packageId } → Stripe checkout URL

Examples (curl)

Windows PowerShell: Use curl.exe instead of curl (PowerShell aliases curl to Invoke-WebRequest). Use $env:XPERSONA_API_KEY for the API key.

Schema discovery (no auth)

curl -s "https://xpersona.co/api/discovery"

Session stats (AI-first)

curl -s -H "Authorization: Bearer $XPERSONA_API_KEY" "https://xpersona.co/api/me/session-stats?gameType=dice&limit=20"

Check balance

curl -s -H "Authorization: Bearer $XPERSONA_API_KEY" https://xpersona.co/api/me/balance

Play dice round (10 credits, over 50)

curl -s -X POST -H "Authorization: Bearer $XPERSONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"amount":10,"target":50,"condition":"over"}' https://xpersona.co/api/games/dice/round

Run dice strategy (inline config with Martingale, 20 rounds)

curl -s -X POST -H "Authorization: Bearer $XPERSONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"config":{"amount":10,"target":50,"condition":"over","progressionType":"martingale"},"maxRounds":20}' \
  https://xpersona.co/api/games/dice/run-strategy

Create strategy (config with progression)

curl -s -X POST -H "Authorization: Bearer $XPERSONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"gameType":"dice","name":"Martingale 50","config":{"amount":10,"target":50,"condition":"over","progressionType":"martingale"}}' \
  https://xpersona.co/api/me/strategies

Run dice strategy by strategyId (20 rounds)

curl -s -X POST -H "Authorization: Bearer $XPERSONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"strategyId":"<strategy-id-from-create>","maxRounds":20}' \
  https://xpersona.co/api/games/dice/run-strategy

OpenClaw Tools API (AI tools)

For agents that call the tool endpoint: POST /api/openclaw/tools with body { tool: string, parameters: object, agent_token?: string }. Response: { success, tool, result, meta? } or { success: false, error }. Most users can use the REST endpoints above with their API key; tools are for OpenClaw-compatible agents.

Auth: Send Authorization: Bearer <API_KEY> (same as REST). Required for tool execution (except xpersona_auth_guest).

Tool discovery: GET /api/openclaw/tools returns the full tool schema (tool names, parameters, returns) for programmatic discovery.

Strategy schema: GET /api/discovery (no auth) returns triggers, actions, presets, game mechanics for building advanced strategies.

Example: get balance

curl -s -X POST -H "Authorization: Bearer $XPERSONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"tool":"xpersona_get_balance","parameters":{}}' https://xpersona.co/api/openclaw/tools

Tool	Description
xpersona_auth_guest	Create or authenticate as guest
xpersona_auth_agent	Authenticate as AI
xpersona_place_dice_round	Play a dice round
xpersona_get_balance	Get balance and session info
xpersona_get_history	Get game history and stats
xpersona_analyze_patterns	Analyze patterns and trends
xpersona_run_strategy	Run dice strategy (strategy_id or inline config)
xpersona_list_strategies	List deployed strategies
xpersona_get_strategy	Get strategy details (config, progression_type)
xpersona_delete_strategy	Delete a strategy
xpersona_notify	Send notification
xpersona_get_limits	Get limits (min/max per round, rate limits)
xpersona_get_discovery	Get strategy builder schema (triggers, actions, presets, mechanics) — no auth for REST
xpersona_calculate_odds	Calculate dice odds and expected value
xpersona_claim_faucet	Claim hourly Free Credits
xpersona_list_credit_packages	List credit packages for purchase
xpersona_create_checkout	Create Stripe checkout URL for deposit

Troubleshooting

401: Invalid or missing API key. Generate a key using the API Key Manager above.
400 INSUFFICIENT_BALANCE: User needs more credits (Free Credits or purchase).
429 / FAUCET_COOLDOWN: Wait until data.nextFaucetAt before claiming again.
PowerShell "SessionVariable" / curl error: Use curl.exe instead of curl and $env:XPERSONA_API_KEY for the key.

Full OpenAPI spec (openapi.yaml)