SentiMove

Python client for SentiMove intelligence reports. One report includes an asset's events and overall analysis for an inclusive 25-block period and costs one Yototec credit. The full current 15-asset overview costs 15 credits. Account, ticker and report-availability reads are free.

Installation and account

python -m pip install git+https://github.com/Yototec/sentimove-sdk.git

Connect your Ethereum-compatible wallet at Yototec Credits to initialize your permanent API key and one-time 1,000-credit grant. Reconnecting reuses the same key and balance. For additional credits, email info@yototec.com with your needs.

Keep the key in a secret store or environment variable. Every SDK request sends it in Authorization: Bearer; it never appears in the URL. Previous SentiChain credentials are retired. Website wallet sessions and SDK access use the same account balance.

Buy one complete report

import os
from sentimove import SentiMoveClient

with SentiMoveClient(api_key=os.environ["YOTOTEC_API_KEY"]) as client:
    account = client.get_account()  # Free, also available at zero credits.
    print(account.credits, account.available_credits)

    # Free discovery provides windows, revision, readiness, limitations and price.
    metadata = client.list_report_metadata(tickers=["BTC"], limit=1)
    if metadata:
        item = metadata[0]
        report = client.get_report("BTC", item["chunk_start"], item["chunk_end"])
        for event in report.events:
            print(event.timestamp, event.type, event.sentiment, event.summary)
        print(report.signal.direction, report.signal.confidence, report.signal.rationale)
        print(report.report_status, report.limitations, report.report_revision)
        print(report.billing.credits_charged, report.billing.credits_remaining)

get_report() makes one purchase. Accessing report.events and report.signal makes no further requests. Calling get_report() again intentionally buys the report again, even when its revision is unchanged. Compare free metadata against the last window/revision you consumed before buying new content.

A useful limited report has report_status="limited" and explains its limitations. Its signal may have direction=None and confidence=None while retaining substantive analysis, categories and patterns. The SDK preserves those null values. A ready signal uses LONG, SHORT or FLAT, with numerical confidence from 0 to 1. Unavailable reports raise an error without returning report content or charging credits.

Full overview

snapshot = client.get_latest_snapshot()
print(snapshot.chunk_start, snapshot.chunk_end)
print(snapshot.billing.credits_charged, snapshot.billing.credits_remaining)
for report in snapshot.assets:
    print(report.ticker, report.signal.rationale)

Run this while the client is open. A snapshot includes all active assets in one coherent period, including useful limited reports. Billing is on snapshot.billing; individual snapshot assets have billing=None. An unavailable asset or insufficient balance rejects the entire purchase without content or debit. For example, a 15-asset purchase with 14 credits leaves all 14 credits available. Use free metadata to identify a smaller available report to request individually.

Retries and errors

Each get_report() or get_latest_snapshot() call creates one UUID in Idempotency-Key. Connection failures and timeouts retry at most twice by default, reusing that UUID and the same request. HTTP errors are returned immediately. A later intentional purchase receives a new UUID.

You can explicitly supply operation_id to resume the same purchase after an uncertain transport outcome. Keep its exact ticker/window or snapshot request. Reusing that ID for different resources is a conflict. Latest-snapshot retries remain bound to the original operation's frozen period, even if a newer period becomes available.

from uuid import uuid4
from sentimove import APIError, AuthenticationError, InsufficientCreditsError

operation_id = str(uuid4())  # Persist alongside the exact requested resource.
try:
    report = client.get_report("BTC", 130175, 130199, operation_id=operation_id)
except InsufficientCreditsError as exc:
    print(exc.required_credits, exc.available_credits)  # Integers; no purchase occurred.
except AuthenticationError:
    print("Check your Yototec API key.")
except APIError as exc:
    # Retain this ID for recovery; do not automatically start another purchase.
    print(exc.status_code, exc.code, exc.operation_id)

Successful paid results expose Billing(credits_charged: int, credits_remaining: int, operation_id: str) parsed from X-Yototec-Credits-Charged, X-Yototec-Credits-Remaining and X-Yototec-Operation-Id. Invalid report or billing responses raise APIError(code="invalid_response"); validated billing is retained on exc.billing when available. Transport errors use code="transport_error". Keys and raw transport exception messages are excluded from SDK errors.

API reference

SentiMoveClient(api_key, base_url="https://api.sentimove.com", timeout=30.0, transport_retries=2) supports context-manager use and close(). Timeouts are positive seconds; transport_retries is an integer from 0 to 5. Redirects are rejected to keep credentials at the configured endpoint.

Ticker symbols are normalized to uppercase. Report windows must begin at a multiple of 25 and end 24 blocks later. Metadata accepts 1 to 100 rows; omit tickers for all active assets. before_chunk filters prior windows. Metadata never includes event text, signals or embeddings.

Report contains ticker, chunk boundaries, status, limitations, opaque revision, events, signal and optional billing. Each event retains timestamp, type, sentiment and summary. Signal retains direction, confidence, rationale, category summaries and Pattern entries with keywords, event indices and descriptions.

Updating existing integrations

This release replaces public component reads and old credentials. Replace get_events(ticker) and get_signal(ticker) with a single get_report() followed by local report.events and report.signal access. The separate component methods, ticker-request method and former package aliases are removed. Enroll a Yototec account and configure its API key before using the client.

The service uses https://api.sentimove.com; configured API host aliases enforce the same access policy. The SDK does not provide live asset-header prices.

Verify locally without production accounts or charges:

python -m unittest discover -s tests -v
python -m build

The contract tests use a local HTTP server and isolated test-only credentials and balances.

Links

• SentiMove
• Yototec Credits
• Source
• Package registry

MIT License. See LICENSE.