Kronos MCP

Previsões financeiras multi-ativos via micropagamentos x402 — 32 ferramentas para cripto, commodities e ações pré-mercado

Ver em seshat.marketsExperimente este MCPPatrocinado

Documentação

Crie com Kronos

Use a API gratuita para avaliar a Kronos primeiro, depois deixe um agente pagar por requisição com x402. A Kronos nunca cria, financia, recupera ou armazena uma carteira de comprador — traga a sua própria.

Comece grátis

Descubra produtos e teste a saída BTC atrasada sem conta, chave de API ou carteira.

Experimente agora

Grátis — catálogo e listagem completa de produtos

curl https://kronos.seshat.markets/api/feeds/kronos/catalog

Grátis — amostra BTC atrasada (todos os 5 períodos)

curl https://kronos.seshat.markets/api/feeds/kronos/sample/btc_usdt

curl https://kronos.seshat.markets/api/feeds/kronos/risk

Leia a especificação OpenAPI, o registro de agentes e o início rápido para agentes para a referência completa.

Como o x402 funciona

Seu agente solicita um endpoint pago.
A Kronos retorna HTTP 402 com um requisito de pagamento assinado: preço, ativo USDC, destino e rede.
A carteira controlada pelo comprador assina uma autorização.
O cliente tenta novamente com o payload de pagamento e recebe o resultado.

Nenhuma conta Kronos ou saldo Kronos pré-pago é necessário. A carteira do comprador ainda precisa de USDC suficiente para os dados solicitados. Dependendo do esquema de pagamento aceito, o facilitador pode cobrir o gás da rede; isso não cobre o preço dos dados.

Padrão SDK Node / TypeScript

Use uma carteira de comprador que você controla. A chave privada permanece no seu runtime local e nunca deve ser commitada, registrada em logs ou colada em chat.

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:84532', client: new ExactEvmScheme(account) }],
});

const response = await fetchWithPayment(
  'https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt?timeframes=1h'
);
const forecast = await response.json();

Use exatamente a rede e o ativo anunciados no desafio 402 ao vivo. Nunca codifique IDs de chain ou endereços de contratos — sempre leia-os do requisito de pagamento retornado pela Kronos.

Python

Use o SDK Python oficial x402 para tratamento automático de 402, ou lide com o desafio manualmente com requests / httpx.

Com o SDK Python x402 (automático)

# pip install x402-requests
from x402.requests import wrap_requests_with_payment
import os

# Buyer wallet private key — keep secret, never commit
session = wrap_requests_with_payment(os.environ["BUYER_PRIVATE_KEY"])

response = session.get(
    "https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt",
    params={"timeframes": "1h"}
)
forecast = response.json()
print(forecast["consensus"]["direction"])  # "LONG" or "SHORT"

Tratamento manual de 402 com requests

import requests

url = "https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt"
params = {"timeframes": "1h"}

# Step 1: request the endpoint — get 402 challenge
resp = requests.get(url, params=params)
if resp.status_code == 402:
    challenge = resp.json()
    # challenge contains: price, accepts (asset, network, scheme),
    # payTo (destination address), x402-version, etc.
    print(f"Payment required: {challenge['price']}")

    # Step 2: sign payment with your wallet (EVM or Solana)
    # Use web3.py (EVM) or solana.py (Solana) to sign
    payment_header = sign_payment(challenge)  # your signing logic

    # Step 3: retry with X-PAYMENT header
    resp = requests.get(url, params=params, headers={
        "X-PAYMENT": payment_header,
        "X-REQUEST-ID": resp.headers.get("X-REQUEST-ID", "")
    })

if resp.status_code == 200:
    forecast = resp.json()
    print(forecast["consensus"]["direction"])

curl — endpoint pago de ponta a ponta

Fluxo completo: requisição inicial → desafio 402 → assinar pagamento → tentar novamente com cabeçalho de pagamento.

# 1. Request the endpoint — receive 402 challenge
curl -s https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt?timeframes=1h \
  -D headers.txt -o challenge.json
# headers.txt contains X-REQUEST-ID, challenge.json has payment requirements

# 2. Sign payment (use x402 CLI, your wallet, or SDK)
#    This produces a base64-encoded payment header
PAYMENT=$(x402 sign --challenge challenge.json --key $BUYER_PRIVATE_KEY)
REQUEST_ID=$(grep -i X-REQUEST-ID headers.txt | awk '{print $2}' | tr -d '\r')

# 3. Retry with payment header
curl -s https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt?timeframes=1h \
  -H "X-PAYMENT: $PAYMENT" \
  -H "X-REQUEST-ID: $REQUEST_ID" \
  -H "Content-Type: application/json" | jq .consensus.direction

Endpoints gratuitos (catálogo, amostra, risco, pré-visualização de precisão, pré-visualização de regime) não exigem pagamento — apenas curl diretamente.

Uso com MCP

Nenhuma instalação local persistente e nenhum servidor hospedado pelo usuário são necessários. Adicione a configuração abaixo e npx busca e inicia automaticamente o conector leve kronos-mcp via stdio — não há porta, daemon ou infraestrutura para o usuário manter. Ferramentas gratuitas funcionam sem carteira: kronos_catalog, kronos_sample e kronos_risk. Ferramentas pagas podem pagar automaticamente apenas quando o operador configura um signatário comprador local.

{
  "mcpServers": {
    "kronos": {
      "command": "npx",
      "args": ["-y", "kronos-mcp"]
    }
  }
}

Para pagamentos x402 automatizados, defina uma ou ambas as variáveis no ambiente do processo MCP local: KRONOS_X402_EVM_PRIVATE_KEY para pagamentos EVM compatíveis com Base e KRONOS_X402_SOLANA_PRIVATE_KEY para pagamentos Solana. Estas são segredos do comprador; nunca são enviados à Kronos como chaves privadas.

Uso com A2A (Agente para Agente)

A Kronos expõe um endpoint A2A JSON-RPC 2.0 em POST https://kronos.seshat.markets/a2a. Qualquer agente compatível com A2A pode descobrir a Kronos via a2aregistry.org ou o cartão de agente e invocar previsões sem escrever código de integração REST personalizado.

Métodos suportados

01 SendMessage / message/send

Envie uma mensagem em linguagem natural ou estruturada. A Kronos analisa a intenção (endpoint + símbolo) e retorna um Task com a previsão como um Artifact.

02 GetTask / tasks/get

Recupere o estado e os artefatos de uma tarefa criada anteriormente.

03 GetExtendedAgentCard

Retorna o cartão completo do agente com habilidades, capacidades e configuração de pagamento.

Início rápido com curl

# Get the agent card
curl -X POST https://kronos.seshat.markets/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"GetExtendedAgentCard"}'

# Request a forecast (free endpoint example)
curl -X POST https://kronos.seshat.markets/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"Get risk state"}]}}}'

# Request a paid forecast (requires x402 payment)
curl -X POST https://kronos.seshat.markets/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"Predict BTC_USDT for next 24h"}]}}}'

Formato de resposta

Requisições bem-sucedidas retornam um objeto Task com status.state = "completed" e o payload JSON da Kronos dentro de artifacts[0].parts[0].content:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "task": {
      "id": "uuid",
      "status": { "state": "completed" },
      "artifacts": [{
        "name": "kronos-risk",
        "parts": [{
          "kind": "data",
          "content": { /* Kronos JSON payload */ }
        }]
      }]
    }
  }
}

Pagamento para endpoints pagos

Quando uma mensagem mapeia para um endpoint pago da Kronos (ex.: predict, signals, accuracy), a tarefa retorna com status.state = "auth-required" e a resposta HTTP inclui os cabeçalhos padrão payment-required e www-authenticate para x402. O chamador assina o pagamento USDC e tenta novamente com um cabeçalho payment-signature, que a Kronos encaminha para o endpoint subjacente.

Análise de intenção

A Kronos extrai o endpoint e o símbolo do texto da mensagem. Exemplos:

"Predict BTC_USDT for next 24h" → /api/feeds/kronos/predict/btc_usdt
"Get trading signals for ETH" → /api/feeds/kronos/agent/signals
"Get calibration metrics" → /api/feeds/kronos/accuracy
"Market regime detection" → /api/feeds/kronos/regime
JSON: {"endpoint":"predict","symbol":"sol_usdt"} → modo estruturado

Usando o SDK Python A2A

from a2a.sdk import A2AClient, Message, TextPart

client = A2AClient("https://kronos.seshat.markets/a2a")

# Get the agent card
card = await client.get_card()

# Send a forecast request
msg = Message(role="user", parts=[TextPart(text="Predict BTC_USDT for next 24h")])
response = await client.send_message(msg)

# Access the forecast artifact
task = response.task
if task.status.state == "completed":
    forecast = task.artifacts[0].parts[0].content
    print(forecast)

O cartão do agente é publicado em /.well-known/agent.json.

Prepare uma carteira de agente

Esta é uma configuração operada pelo comprador, não um serviço da Kronos. Use uma carteira ou sistema de gerenciamento de chaves que você já controla.

01 Separe a carteira do agente

Não dê a um agente autônomo acesso a uma carteira pessoal ou de tesouraria. Financie apenas o valor que o operador está disposto a deixar o agente gastar.

02 Financie com o USDC aceito

A Kronos aceita USDC na Base e Solana — a rede exata é definida pelo desafio 402 atual.

03 Mantenha a chave local

Use um armazenamento de segredos local ou injeção de ambiente. Nunca faça commit, adicione a arquivos de configuração MCP rastreados por git, ou forneça ao suporte da Kronos.

04 Teste primeiro

Use ferramentas gratuitas antes de habilitar pagamentos automatizados.

Segurança do agente

Revise os preços dos endpoints no catálogo antes da automação.
Use uma carteira dedicada e escolha seu nível de financiamento você mesmo; a Kronos não impõe um orçamento diário restritivo.
Mantenha os limites de taxa da API existentes em mente, especialmente para chamadas de playground GPU.
Monitore a atividade da carteira do comprador de forma independente e rotacione sua chave se houver suspeita de comprometimento.
Trate as previsões como sinais de pesquisa, nunca como instruções de negociação.

Reembolsos e disputas

Pagamentos x402 são transferências USDC on-chain liquidadas pelo facilitador PayAI. Cada pagamento está vinculado a uma requisição específica via cabeçalho X-Request-Id ecoado na resposta.

Entrega bem-sucedida: Se o endpoint retornar HTTP 200 com dados válidos, o pagamento é final. Nenhum reembolso está disponível para previsões que se revelarem incorretas — a Kronos fornece sinais de pesquisa, não garantias.
Falha do handler após pagamento antecipado: Se o endpoint retornar HTTP 5xx após o pagamento ter sido liquidado (fluxo antecipado), entre em contato com o suporte com o X-Request-Id e o hash da transação. Reembolsaremos o valor total para a carteira do pagador dentro de 5 dias úteis.
Falha de liquidação do facilitador: Se o facilitador PayAI falhar ao liquidar, o cliente não é cobrado. A resposta 402 inclui o motivo da falha; nenhuma ação é necessária.
Cobranças duplicadas: Se o mesmo hash de transação for usado para múltiplas requisições, nosso sistema detecta e alerta a equipe. Entre em contato com o suporte se você acredita que foi cobrado duas vezes pela mesma requisição.
Janela de disputa: Disputas devem ser submetidas dentro de 30 dias do pagamento. Inclua o X-Request-Id, hash da transação e rede (Solana ou Base).

Reembolsos são transferências on-chain manuais. A Kronos não pode reverter uma transação on-chain liquidada; em vez disso, enviamos uma transferência USDC equivalente de volta ao endereço do pagador.

Catálogo de erros

Toda resposta da API usa códigos de status HTTP padrão. Corpos de erro são JSON com error (código legível por máquina) e detail opcional (explicação legível por humanos).

Status	Código de erro	Quando	Como lidar
402	`payment_required`	Endpoint pago solicitado sem pagamento válido. O corpo da resposta contém o desafio x402: `price`, `accepts` (ativo, rede, esquema), `payTo` (destino), `x402-version`.	Analise o desafio, assine um pagamento com sua carteira de comprador e tente a mesma requisição novamente com cabeçalhos `X-PAYMENT` e `X-REQUEST-ID`. Use `@x402/fetch` (JS) ou `x402-requests` (Python) para automatizar isso.
429	`rate_limited`	Muitas requisições. Cada endpoint tem seu próprio limite (veja a tabela de limites de taxa). `detail` explica qual limite foi atingido.	Recue e tente novamente. O cabeçalho `Retry-After` (quando presente) indica segundos de espera. Para predict, use respostas em cache (omita `?refresh=true`) — o TTL do cache é de 5–15 min por período.
503	`kronos_disabled`	O serviço Kronos está desabilitado no lado do servidor (`KRONOS_ENABLED=false`). Todos os endpoints pagos retornam isso.	Tente novamente mais tarde. Este é um estado de configuração do servidor, não um erro do cliente. Verifique /risk (grátis) para status operacional.
503	`forecast_unavailable`	Não foi possível gerar ou recuperar uma previsão. O símbolo pode não ter dados de candle suficientes na exchange upstream.	Tente um símbolo diferente ou aguarde a exchange upstream fornecer mais dados. Símbolos sob demanda podem precisar que sua primeira previsão seja acionada manualmente.
500	`kronos_error`	Erro interno do servidor. Para endpoints de fluxo de pagamento `upfront`, a resposta inclui `retry_token` e `refund_reference`.	Se `retry_token` estiver presente, tente a mesma requisição novamente com o cabeçalho `X-Retry-Token` (uso único, TTL de 1h). Se `refund_reference` estiver presente, entre em contato com o suporte com esse hash de tx para reembolso.
404	`unknown_symbol`	O símbolo solicitado não está no catálogo da Kronos e a descoberta sob demanda falhou (símbolo Gate.io inválido ou não suportado).	Verifique /catalog para símbolos suportados. Para sob demanda, garanta que o símbolo exista na Gate.io.
400	`missing_text` / `missing_query` / `invalid_agent_id`	Parâmetro obrigatório ausente ou inválido. `detail` explica o que é necessário.	Corrija os parâmetros da requisição e tente novamente. Nenhum pagamento é cobrado para erros 400.

Tokens de nova tentativa (somente fluxo antecipado)

Quando um erro 5xx ocorre após um pagamento upfront ter sido liquidado (predict, forecast-distribution, playground, market-brief, similar-markets, outcome-stats, behavioral-correlations, rationale-novelty), a resposta inclui:

retry_token — token de uso único, TTL de 1h. Envie no cabeçalho X-Retry-Token na sua próxima requisição para ignorar o pagamento.
refund_reference — hash de tx on-chain do pagamento liquidado. Cite isso ao solicitar um reembolso manual.

Para endpoints de fluxo authorization (data/analysis), o pagamento só é liquidado em respostas bem-sucedidas (2xx) — nenhum reembolso é necessário em 5xx.

Páginas de referência da API

Documentação detalhada para cada endpoint e tópico: