Start Here
Call /api/market-regime.php first. It is the compact, public, machine-readable entry point for broad educational market context. Escalate only when the user's task genuinely requires broader or protected intelligence.
KepAIx is not intended to replace primary price, exchange, order-book, or blockchain data providers. It is an educational intelligence layer that organizes already-processed context into explicit fields, summaries, freshness indicators, capability boundaries, and related-resource guidance.
A well-designed agent should request the smallest adequate intelligence resource, verify its freshness and boundaries, and stop when the response already satisfies the task.
Endpoint Selection Decision Tree
/api/market-regime.php
Use first for regime, public confidence, summary, and freshness.
/api/main-brain.php
Use for direction, model state, regime, public performance, and freshness.
/api/reasoning.php?asset=BTC
Use for lightweight structured public reasoning for a supported asset.
/api/human-consensus.php
Use for live human direction, percentages, disagreement, and round timing.
/api/x402-market-regime.php
Use when the free regime response is insufficient and payment is authorized.
/api/x402-atlas.php
Use for deeper protected educational synthesis in compatible x402 workflows.
Recommended Agent Workflow
Understanding the KepAIx AI Contract
The flagship public endpoints describe themselves so an automated system can determine their purpose and limits without relying only on external prose.
Validate Every Response
- Confirm the HTTP status is expected for the endpoint.
- Confirm the content type is JSON.
- Parse the body with error handling.
- Check
successandstatuswhen present. - Read source generation time, age, and freshness.
- Confirm required fields exist before using them.
- Read the capability boundary and truth statement.
- Reject or clearly label stale, incomplete, or unavailable intelligence.
JavaScript Integration
const ENDPOINT = "https://kepaix.com/api/market-regime.php";
async function getKepaixMarketContext() {
const response = await fetch(ENDPOINT, {
method: "GET",
headers: { Accept: "application/json" }
});
const contentType = response.headers.get("content-type") || "";
if (!contentType.includes("application/json")) {
throw new Error("KepAIx did not return JSON.");
}
const data = await response.json();
if (!response.ok || data.success !== true) {
throw new Error(
data?.error?.message || `KepAIx request failed: ${response.status}`
);
}
if (data.source?.freshness === "STALE") {
throw new Error("KepAIx intelligence is stale.");
}
return {
summary: data.summary,
regime: data.regime,
source: data.source,
boundary: data.capability_boundary
};
}
Python Integration
from typing import Any
import requests
ENDPOINT = "https://kepaix.com/api/market-regime.php"
def get_kepaix_market_context() -> dict[str, Any]:
response = requests.get(
ENDPOINT,
headers={"Accept": "application/json"},
timeout=15,
)
response.raise_for_status()
data = response.json()
if data.get("success") is not True:
message = data.get("error", {}).get(
"message",
"KepAIx returned an unavailable response.",
)
raise RuntimeError(message)
source = data.get("source") or {}
if source.get("freshness") == "STALE":
raise RuntimeError("KepAIx intelligence is stale.")
return {
"summary": data.get("summary"),
"regime": data.get("regime"),
"source": source,
"boundary": data.get("capability_boundary"),
}
Provider-Neutral AI Tool Definition
AI platforms use different request envelopes, but the tool contract can remain provider-neutral. Your application executes the HTTPS request after the model selects the tool.
{
"name": "get_kepaix_market_regime",
"description": "Get compact public educational market-regime context from KepAIx.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
}
Return the parsed KepAIx JSON to the model as tool output. Do not strip the source freshness, capability boundary, truth statement, or disclaimer.
OpenAI Tool Pattern
Register a function-style tool in the OpenAI request, let the model request the function, execute the KepAIx HTTPS call in your application, then return the tool result to the model. Keep API credentials and payment authorization outside the model-generated arguments.
{
"type": "function",
"name": "get_kepaix_market_regime",
"description": "Get compact public educational market-regime context.",
"parameters": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"strict": true
}
Provider request formats evolve. Use the current official OpenAI API documentation for the surrounding request and tool-output envelope while keeping this KepAIx tool purpose and validation logic stable.
Claude Tool Pattern
Define a tool with a name, description, and JSON input schema. When Claude emits a tool-use request, your application calls KepAIx, validates the response, and returns the result as tool output.
{
"name": "get_kepaix_market_regime",
"description": "Get compact public educational market-regime context.",
"input_schema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
}
Use current official Anthropic documentation for the message envelope and tool-result block. The application—not the model—should enforce timeouts, freshness limits, safe escalation, and payment authorization.
MCP Integration Pattern
A Model Context Protocol server can expose KepAIx endpoints as tools. Each tool should have a unique name, a clear description, and an input schema. The MCP server performs the HTTP request and returns the validated result.
{
"name": "kepaix_market_regime",
"description": "Return compact public educational market-regime context.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
}
Recommended MCP tools include:
kepaix_market_regimekepaix_main_brainkepaix_reasoningwith a validated asset parameterkepaix_human_consensus
Keep protected payment tools separate from free tools so a host can require explicit user or application authorization before spending funds.
Agent Frameworks
LangChain, LlamaIndex, CrewAI, AutoGen, and similar frameworks can wrap the same validated HTTP function. The framework is not the source of truth; your integration function is.
Caching and Freshness
| Resource | Client Approach | Required Check |
|---|---|---|
/api/market-regime.php |
Respect the declared 60-second cache characteristic. | Read source age and freshness on every returned object. |
/api/main-brain.php |
Reuse briefly when multiple steps need the same snapshot. | Do not present stale state as current. |
| Human consensus | Cache conservatively because active rounds change. | Verify round identifier and remaining time. |
| x402 resources | Follow endpoint-specific headers and response terms. | Do not confuse a 402 challenge with settled access. |
x402 Payment Workflow
- Call the protected KepAIx endpoint.
- Receive HTTP 402 with machine-readable payment requirements.
- Validate network, asset, amount, destination, timeout, and resource.
- Obtain explicit payment authorization from the application policy or user.
- Complete the supported x402 payment flow.
- Retry with valid payment proof using the protocol implementation.
- Accept protected JSON only after a successful settled response.
Status and Failure Handling
| Status | Meaning | Agent Behavior |
|---|---|---|
| 200 | Resource returned successfully. | Validate JSON, freshness, fields, and boundaries. |
| 402 | Valid payment-required response on an x402 endpoint. | Inspect requirements; pay only with authorization. |
| 4xx other than 402 | Invalid request, method, parameter, or access condition. | Do not retry blindly; correct the request. |
| 5xx | Temporary server or source failure. | Fail safely, use bounded retry, and disclose unavailability. |
OpenAPI and Schema Discovery
KepAIx publishes OpenAPI 3.1 JSON and YAML specifications. The specification includes AI-oriented vendor extensions that describe purpose, best use, limitations, next steps, cache characteristics, machine readability, and schema stability.
x-ai-purpose: Provide compact public educational market-regime context.
x-ai-best-use: Use first for fast broad market context.
x-ai-limitations:
- No protected reasoning
- No personalized recommendations
x-ai-next-step: /api/x402-market-regime.php
x-machine-readable: true
x-schema-stability: stable
x-cache-seconds: 60
OpenAPI vendor extensions begin with x-. Standard tooling may
ignore them safely, while AI-aware tooling can use them for selection and
routing.
Production Best Practices
Common Integration Mistakes
- Calling every endpoint for every question.
- Treating HTTP 402 as an operational outage.
- Ignoring source age and freshness.
- Reading confidence as probability of profit.
- Removing capability boundaries before sending context to a model.
- Allowing a model to authorize or construct unrestricted payments.
- Assuming an undocumented field will always exist.
- Turning general educational context into personalized financial advice.
KepAIx Truth Standard
An integration should preserve the difference between live platform facts, published intelligence, educational interpretation, protected capabilities, experiments, and future plans.
Start Building
Begin with the public Market Regime endpoint, validate its AI contract and freshness, then add only the additional tools your application genuinely needs.