keelta
Developer documentation

A local connection.
A clear interface.

Run two snapshot reading tools in your AI client. No exchange credentials are needed for the current release.

Current source reference · 21 October 2026

The README and server source implement cycle_state and sentiment using a local snapshot. position_check, rebalance_plan, and execute are stubs with explicit not_implemented results. The repository currently requires access; the public package is not yet available.

Installation

With access to the product repository, obtain a local checkout, open its directory, and run the README commands:

uv sync
uv run keelta-scope

Add the following README block to ~/Library/Application Support/Claude/claude_desktop_config.json. Replace the absolute directory placeholder with your local checkout path.

CLAUDE DESKTOP / README CONFIGURATION
{
  "mcpServers": {
    "keelta-scope": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/keelta-scope", "run", "keelta-scope"]
    }
  }
}

Restart Claude Desktop, then ask: “Call cycle_state and summarise it.”

The future package route is uvx keelta-scope. It is not available until package publication.

Environment variables

The server calls load_dotenv() for local configuration. Copy the repository's .env.example to .env in the checkout when configuring a local run. The two current tools do not consume OKX credentials.

VariableCurrent behavior
KEELTA_TIERSource default: free_delayed. The example file selects pro. pro uses the base snapshot; other values take the delayed-view path described below.
KEELTA_SNAPSHOT_PATHOptional local JSON file path. The default is the repository's data/snapshot.json.
OKX_API_KEYReserved for the planned exchange integration. Not used by the current tools.
OKX_API_SECRETReserved for the planned exchange integration. Leave credentials out of shared files.
OKX_PASSPHRASEReserved for the planned exchange integration.
OKX_SIMULATEDThe example sets 1 for the planned demo request header x-simulated-trading: 1. The current server does not read this variable.

Never commit a populated .env to a repository or paste credentials into an AI conversation.

Five declared tools. Two implemented.

The reference below describes the current source. Reading tools use a static local JSON file; their timestamps describe snapshot data, not a fresh exchange query. See the source repository for the full schema.

cycle_stateLocal snapshot

Read the BTC cycle phase from the local Keelta snapshot.

Inputs
None.
Output fields
as_of, phase, confidence, next_review, delayed, disclaimer, and tier are documented here. For the complete raw schema, see the source. The delayed-view rule below can replace the base reading fields.

sentimentLocal snapshot

Read the Sentinel sentiment snapshot for Chinese-language crypto discourse: a composite score in [-1, 1], its 4h/24h/7d trend, sample size, and timestamp.

Inputs
None.
Output fields
Base result: as_of, composite, trend, sample_size, delayed, disclaimer, tier. The delayed-view rule below can replace the base reading fields.

position_checkNot implemented

Planned: read your own OKX spot position. The current stub does not contact OKX.

Inputs
None.
Output fields
Current result: status: "not_implemented" and planned: "week 1, day 2". The planned field is a source label, not a release commitment.

rebalance_planNot implemented

Planned: prepare a target position and order plan. The current stub only echoes its inputs.

Inputs
target_btc_pct: required number. max_order_usd: number, default 1000.0. No range or account checks are implemented.
Output fields
Current result: status: "not_implemented", planned: "week 1, day 3", and echo containing target_btc_pct and max_order_usd. It issues no confirmation token.

executeNot implemented

Planned: execute a confirmed plan. The current stub places no orders and performs no token validation.

Inputs
confirmation_token: required string.
Output fields
Current result: status: "not_implemented", planned: "week 1, day 3", and token_seen, a boolean indicating whether the supplied string is nonempty. This is not a validity check.
Delayed-view behavior

With pro, the base reading includes tier: "pro". Otherwise, a nonempty delayed block replaces the base reading and receives tier: "free_delayed" plus disclaimer. If no delayed block exists, the base reading is used with tier: "free_delayed". The client does not generate or refresh the snapshot.

Error codes

The current source raises FileNotFoundError if the snapshot is missing. Invalid JSON or absent expected keys can also fail a reading. It does not define a stable product error envelope.

The following codes are planned vocabulary for the exchange integration; the current tools do not emit them:

Planned codeIntended meaning
NO_CREDENTIALSRequired local exchange credentials are absent.
WITHDRAWAL_PERMISSION_DETECTEDA future permission check detects withdrawal access.
OKX_<code>An exchange API error.
TRANSPORTA connection or transport failure.

Creating a read+trade API key on OKX

Reference for the planned integration. The current snapshot tools need no OKX key. Begin with a dedicated Demo Trading key when exchange support is released.

  1. Sign in to OKX and open Trade → Demo Trading.
  2. Open Personal Center → Demo Trading API → Create Demo Trading API Key.
  3. Set a passphrase. Enable Read and Trade; leave Withdraw disabled.
  4. Create the key and securely save its API key, secret key, and passphrase on your own machine. Never paste them into an AI conversation.
  5. Use these credentials only with demo requests carrying x-simulated-trading: 1. The example reserves OKX_SIMULATED=1 for this purpose; exchange support is not yet implemented.

The Trade permission also permits certain account transfers. Disabling Withdraw does not remove every account-level risk. Follow OKX's permission reference and Demo Trading documentation.