Kira AI — Documentation

Overview

Kira AI is a suite of trading agents: TradeGPT (learning & strategy Q&A), ChartSage (AI technical analyst), PulseScout (real-time market radar), and x402 Engine (pay-per-use access & monetization). All responses are generated via the backend at https://kirabackend.onrender.com, which calls OpenAI with your server API key. Frontend never contacts OpenAI directly.

Flow: Connect wallet → Unlock (0.01 SOL via Phantom) → Use module → Frontend calls /agent/run with Bearer token → Backend replies.

Tech stack: Node/FastAPI gateway, x402 middleware, Solana payments, schedulers for 4-hour updates, observability via OpenTelemetry → Grafana.

Modules

TradeGPT (Learning Agent)

Strategy Q&A with examples (“Explain order blocks on SOL”).
Adaptive Daily Quiz (image + multiple choice + direction guess).
Elo-style difficulty & 14-day Guided Practice.

ChartSage (AI Technical Analyst)

Auto detection: bull flag, H&S, triangles, S/R zones, liquidity sweeps.
Human narrative with triggers & invalidations across 15m/1H/4H.
Integrates with your OHLCV ingestor & pattern library.

PulseScout (Real-Time Market Radar)

Scans thousands of pairs/min for volume Z-score, Δ funding, OI spike, liquidity add, whale tx.
Precision-first alerts (Validity ≥ 0.85 from rolling 90-day backtest).
Telegram/Discord notifications + quick chart & trade plan links.

x402 Engine

Implements HTTP 402 Payment Required for pay-per-use data & features.
Auto-unlock third-party paywalls and monetize pro capabilities per call.

Payments (x402)

Per-request tokens

The frontend unlocks a session by paying 0.01 SOL. Backend verifies the on-chain signature via /x402/verify and issues accessToken (JWT). The token is sent as Authorization: Bearer <token> to all API calls.

Key	Description
price_sol	Dynamic price (from /health)
receiver	Solana address to receive SOL
sessionId	Temporary identifier tied to a payment attempt

Third-party paywalls

Provider responds 402 with {amount, chain, memo}.
x402 pays (e.g., USDC on Base/Solana), stores proof.
Gateway retries request with proof header → access granted.

Works great for order-book APIs, options, premium news feeds, etc.

Backend API

GET /health

Returns service status and current pricing.

curl -s https://kirabackend.onrender.com/health | jq

POST /x402/session

Create a payment session before sending the Phantom popup.

curl -sX POST https://kirabackend.onrender.com/x402/session \
  -H "Content-Type: application/json" \
  -d '{ "product":"tradegpt", "chain":"solana", "wallet":"YOUR_SOL_ADDRESS" }'

POST /x402/verify

Verify on-chain signature and issue accessToken.

curl -sX POST https://kirabackend.onrender.com/x402/verify \
  -H "Content-Type: application/json" \
  -d '{ "sessionId":"SESSION_ID", "signature":"SIGNATURE" }'

POST /agent/run

Proxy to OpenAI with your model configuration. Requires Bearer token.

curl -sX POST https://kirabackend.onrender.com/agent/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{ "prompt": "Explain order blocks briefly." }'

401 / 402 handling

401: token missing/expired → prompt user to unlock again.
402: paywall from third-party → x402 middleware executes handshake then retries.

Webhooks

Use Telegram/Discord to publish alerts and summaries.

POST https://api.telegram.org/bot<BOT_TOKEN>/sendMessage
{
  "chat_id": "<CHAT_ID>",
  "text": "[PulseScout] SOL/USDT volume Z-score 3.2σ — bias long above 186, invalidation 182"
}

Discord

POST <DISCORD_WEBHOOK_URL>
{
  "embeds": [{
    "title": "PulseScout: SOL/USDT anomaly",
    "description": "VOL Z-score 3.2σ. Trigger 186.2, invalidation 182.0",
    "color": 1127128,
    "url": "https://www.tradingview.com/chart/?symbol=BINANCE:SOLUSDT"
  }]
}

Install & Deploy

Frontend

Upload single-file pages to your web root (e.g., /tradegpt.html, /chartsage.html).
Ensure assets exist: /assets/logo.png, /assets/phantom.png, /assets/metamask.svg.
Set CORS on backend to allow your origin (e.g., https://kiraai.io).

Backend (Render)

Create a Web Service from your repo.
Set Environment variables (below).
Auto-deploy on commits. Confirm health at /health.

Environment

Key	Example	Description
OPENAI_API_KEY	sk-…	Server key for OpenAI
X402_RECEIVER	FCRJ…Qyu8	Solana address receiving SOL
X402_PRICE_SOL	0.01	Access price per session
ALLOWED_ORIGINS	https://kiraai.io	CORS allow list (comma-separated)
LOG_LEVEL	info	Logging verbosity

Security

Frontend stores only accessToken in localStorage (session-scoped).
Backend validates signatures & token expiry; rotate keys regularly.
Rate-limit per IP & wallet; audit x402 transactions and retries.
Do not expose OpenAI keys in the browser.

Errors & Status Codes

Code	Meaning	Action
200	OK	—
401	Unauthorized / token expired	Prompt user to unlock again
402	Payment Required (provider)	x402 handshake then retry
429	Rate limited	Backoff & retry
5xx	Upstream failure	Failover, alert ops

Schedulers

4-Hour Summaries: Post ChartSage/PulseScout summaries to Telegram/Discord.
Daily Quiz: Generate image questions and evaluate answers.
Use Celery/Temporal workers; store results to ClickHouse/TimescaleDB.

FAQ

Do I need an account for premium data?

No. x402 pays providers on demand and retries with proof; users don’t register anywhere.

Which wallets are supported?

Phantom (Solana) for payments. MetaMask is supported for sign-in only.

Where do model settings live?

On the backend. Adjust model, temperature, and system prompts server-side.

Changelog (public)

v1 — Initial public docs. TradeGPT, ChartSage, PulseScout & x402 pages live. Price 0.01 SOL.