# Kortex

> Kortex tells an agent which x402 service actually works, from evidence: uptime measured over time, a valid 402, and settlements proven on-chain.

## Why this exists

- Every payment you make is a bet on a stranger. There is nothing between you and a URL that takes your money and returns nothing.
- Directories tell you what exists. Measured across 1,015 listed x402 services, only 25% answer with a payment requirement at all.
- A service can claim anything in its own description. It cannot fake having been paid, by other wallets, on-chain.
- Ask Kortex before you pay, and report what happened after. Reporting is free, and only counts when the payment is found on-chain.

## Using it, with no human in the loop

1. `POST /v1/identity` with your wallet address and an EIP-191 signature. Free, no account, no human. You get a handle and a bearer token.
2. `GET /v1/check?resource=<url>` before paying a service you have not used. You get a verdict, a score, and the facts behind both.
3. `GET /v1/resolve?need=<what you want done>` when you do not have a URL yet. One entry per operator, ranked by evidence rather than by listing.
4. `POST /v1/report` after you pay. Free, and only counted once the payment is found on-chain — which is what stops anyone smearing a competitor.

## What the score is made of

- Uptime, from probes taken over time and kept, not overwritten.
- Whether the endpoint returns a valid 402 at all, checked first-hand rather than taken from a directory.
- Settlements to its payout address on Base, and how many distinct wallets they came from.
- Whether the payout address or the price has moved recently. A payout address that changes is the strongest warning there is.
- Verified reports from agents that actually paid.

Nothing rewards being listed in more directories. That is the metric every directory already optimises, and the one a spammer can move for free.

## Prices

| Operation | Price (USD) | What it does |
| --- | --- | --- |
| `capabilities` | free | Return the full machine-readable manifest of Kortex: every operation, its price in USD, its input schema and how to pay. Free. |
| `identity.create` | free | Turn a wallet address into a permanent Kortex identity and an API token. Free, and grants a small trial credit. |
| `whoami` | free | Your handle, wallet, balance and usage. Free. |
| `credit.deposit` | free | Buy Kortex credit with USDC on Base over x402. One on-chain settlement, then every call is debited off-chain. |
| `resolve` | 0.005000 | Describe what you need in plain language and get back x402 services ranked by evidence: how much of the time they have been up, whether they answer with a valid 402, and how many distinct wallets have actually paid them on-chain. One entry per operator, not per URL. |
| `check` | 0.002000 | Everything Kortex knows about a single resource URL: whether it is up, whether its 402 is well formed, what it quotes, and whether its payout address has ever been paid on-chain. Returns a verdict, not just data. |
| `compare` | 0.003000 | Score two or more resource URLs side by side on the same evidence, and say which one to pay. |
| `history` | 0.002000 | The full time series behind a score: every probe outcome, every price and payout-address change, and the on-chain settlement history of the address it pays to. |
| `watch` | 0.005000 | Register interest in a service. Kortex records a watch and reports what has changed — price, payout address, or availability — the next time you ask. |
| `report` | free | Tell Kortex that you paid a service and what you got. Free, and only counted once the payment is found on-chain — so a report costs at least the price of the call it describes. |

## Paying

Payment is x402 (USDC on eip155:8453). Deposit once, spend per call.
Per-call on-chain settlement would cost more than most calls are worth, so Kortex keeps a prepaid balance and debits it off-chain.

## Endpoints

- Manifest: https://kortex.rohnelt.dev/v1/capabilities
- OpenAPI: https://kortex.rohnelt.dev/openapi.json
- MCP (streamable HTTP): https://kortex.rohnelt.dev/mcp
- x402 discovery: https://kortex.rohnelt.dev/.well-known/x402


## Full operation reference

### capabilities

Return the full machine-readable manifest of Kortex: every operation, its price in USD, its input schema and how to pay. Free.

**When to use:** Call this first if you have never used Kortex and want to know what it can do and what it costs.
**Price:** free
**HTTP:** GET https://kortex.rohnelt.dev/v1/capabilities
**MCP tool:** `capabilities`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
```

**Example response**
```json
{
  "service": "Kortex",
  "operations": [
    "resolve",
    "check",
    "report"
  ]
}
```

### identity.create

Turn a wallet address into a permanent Kortex identity and an API token. Free, and grants a small trial credit.

**When to use:** Call this once, before anything else. You need the returned token for every other call. No account, no email, no human.
**Price:** free
**HTTP:** POST https://kortex.rohnelt.dev/v1/identity
**MCP tool:** `identity.create`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "Your EVM wallet address. This is your permanent identity."
    },
    "signature": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]+$",
      "description": "EIP-191 personal_sign of the message field, proving you control the wallet."
    },
    "message": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200,
      "description": "Must contain your wallet address and a timestamp within the last 10 minutes."
    },
    "label": {
      "description": "A name for your own reference.",
      "type": "string",
      "maxLength": 64
    }
  },
  "required": [
    "wallet",
    "signature",
    "message"
  ]
}
```

**Example response**
```json
{
  "handle": "swift-heron-4f2a",
  "token": "ktx_sk_...",
  "balance_usd": "0.020000"
}
```

### whoami

Your handle, wallet, balance and usage. Free.

**When to use:** Call this to check your balance before a run, or to confirm your token still works.
**Price:** free
**HTTP:** GET https://kortex.rohnelt.dev/v1/whoami
**MCP tool:** `whoami`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
```

**Example response**
```json
{
  "handle": "swift-heron-4f2a",
  "balance_usd": "0.870000",
  "trial": false
}
```

### credit.deposit

Buy Kortex credit with USDC on Base over x402. One on-chain settlement, then every call is debited off-chain.

**When to use:** Call when your balance is low. Operations cost fractions of a cent, so a single deposit covers hundreds of them.
**Price:** free
**HTTP:** POST https://kortex.rohnelt.dev/v1/credit/deposit
**MCP tool:** `credit.deposit`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "amount_usd": {
      "description": "One of 1, 5 or 20. Defaults to 1.",
      "type": "string"
    }
  }
}
```

**Example response**
```json
{
  "credited_usd": "1.000000",
  "balance_usd": "1.020000",
  "tx": "0x..."
}
```

### resolve

Describe what you need in plain language and get back x402 services ranked by evidence: how much of the time they have been up, whether they answer with a valid 402, and how many distinct wallets have actually paid them on-chain. One entry per operator, not per URL.

**When to use:** Call this before paying a service you have not used, and instead of taking the first result from a directory. Of the services listed as x402 today, measured across 1,015 of them, only 25% actually answer with a payment requirement — the rest are up but sell nothing.
**Price:** US$0.005000
**HTTP:** GET https://kortex.rohnelt.dev/v1/resolve
**MCP tool:** `resolve`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "minLength": 3,
      "maxLength": 200,
      "description": "What you want done, in plain language. Example: scrape a web page and return clean text."
    },
    "limit": {
      "default": 5,
      "description": "How many candidates to return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "max_price_usd": {
      "description": "Skip anything that quotes more than this per call.",
      "type": "string"
    },
    "require_paid": {
      "default": true,
      "description": "Only return services with at least one on-chain settlement. Turn off to see untested ones too.",
      "type": "boolean"
    }
  },
  "required": [
    "need"
  ]
}
```

**Example response**
```json
{
  "need": "scrape a web page",
  "results": [
    {
      "resource": "https://example.com/v1/scrape",
      "service_name": "Example Scraper",
      "score": 84.2,
      "price_usd": "0.002000",
      "evidence": {
        "uptime_30d": 0.99,
        "payers_30d": 41,
        "settlements_30d": 1368,
        "median_latency_ms": 221,
        "last_paid": "2026-08-24T19:02:11Z"
      }
    }
  ]
}
```

### check

Everything Kortex knows about a single resource URL: whether it is up, whether its 402 is well formed, what it quotes, and whether its payout address has ever been paid on-chain. Returns a verdict, not just data.

**When to use:** Call this when you already have a URL and want to know whether sending money to it is a good idea. Worth it above roughly US$0.05 a call; below that the check costs more than the risk.
**Price:** US$0.002000
**HTTP:** GET https://kortex.rohnelt.dev/v1/check
**MCP tool:** `check`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "The exact URL you are about to pay, including the path."
    },
    "probe_now": {
      "default": false,
      "description": "Hit the endpoint live instead of using the most recent scheduled probe.",
      "type": "boolean"
    }
  },
  "required": [
    "resource"
  ]
}
```

**Example response**
```json
{
  "resource": "https://example.com/v1/scrape",
  "verdict": "pay",
  "score": 84.2,
  "reasons": [
    "up on 99% of probes over 30 days",
    "41 distinct wallets paid it in 30 days"
  ],
  "evidence": {
    "uptime_30d": 0.99,
    "payers_30d": 41,
    "pay_to": "0xabc...",
    "price_usd": "0.002000"
  }
}
```

### compare

Score two or more resource URLs side by side on the same evidence, and say which one to pay.

**When to use:** Call this when you already have a shortlist and need to pick. Cheaper than calling check once per URL.
**Price:** US$0.003000
**HTTP:** POST https://kortex.rohnelt.dev/v1/compare
**MCP tool:** `compare`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "resources": {
      "minItems": 2,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 2048,
        "format": "uri",
        "description": "The exact URL you are about to pay, including the path."
      },
      "description": "The URLs to rank."
    }
  },
  "required": [
    "resources"
  ]
}
```

**Example response**
```json
{
  "best": "https://example.com/v1/scrape",
  "ranked": [
    {
      "resource": "https://example.com/v1/scrape",
      "score": 84.2,
      "verdict": "pay"
    },
    {
      "resource": "https://other.example/v1/scrape",
      "score": 12,
      "verdict": "avoid"
    }
  ]
}
```

### history

The full time series behind a score: every probe outcome, every price and payout-address change, and the on-chain settlement history of the address it pays to.

**When to use:** Call this when a verdict surprises you, or before committing to a service you plan to depend on. This is the evidence itself rather than the summary.
**Price:** US$0.002000
**HTTP:** GET https://kortex.rohnelt.dev/v1/history
**MCP tool:** `history`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "The exact URL you are about to pay, including the path."
    },
    "days": {
      "default": 30,
      "description": "How far back to look.",
      "type": "integer",
      "minimum": 1,
      "maximum": 90
    }
  },
  "required": [
    "resource"
  ]
}
```

**Example response**
```json
{
  "resource": "https://example.com/v1/scrape",
  "uptime": [
    {
      "day": "2026-08-24",
      "probes": 2,
      "reachable": 2
    }
  ],
  "changes": [
    {
      "at": "2026-08-12T09:00:00Z",
      "field": "pay_to",
      "from": "0xaaa...",
      "to": "0xbbb..."
    }
  ],
  "settlements": {
    "count_30d": 1368,
    "payers_30d": 41,
    "first": "2026-06-02T11:04:00Z"
  }
}
```

### watch

Register interest in a service. Kortex records a watch and reports what has changed — price, payout address, or availability — the next time you ask.

**When to use:** Call this for a service you depend on. A payout address that moves is the strongest warning signal there is, and you will not notice it by yourself.
**Price:** US$0.005000
**HTTP:** POST https://kortex.rohnelt.dev/v1/watch
**MCP tool:** `watch`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "The exact URL you are about to pay, including the path."
    },
    "callback_url": {
      "description": "Optional. If set, Kortex POSTs here when something changes.",
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "resource"
  ]
}
```

**Example response**
```json
{
  "watching": "https://example.com/v1/scrape",
  "watch_id": "wch_01H..."
}
```

### report

Tell Kortex that you paid a service and what you got. Free, and only counted once the payment is found on-chain — so a report costs at least the price of the call it describes.

**When to use:** Call this after any paid call that went wrong, and after ones that went right. It is free, it makes every later verdict better, and the evidence it adds is the kind no probe can produce.
**Price:** free
**HTTP:** POST https://kortex.rohnelt.dev/v1/report
**MCP tool:** `report`

**Input schema**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "The exact URL you are about to pay, including the path."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "ok",
        "no_response",
        "wrong_output",
        "overcharged",
        "never_delivered"
      ],
      "description": "What actually happened after you paid."
    },
    "detail": {
      "description": "What happened, in your own words.",
      "type": "string",
      "maxLength": 500
    },
    "tx_hash": {
      "description": "The settlement transaction, if you have it. Speeds up verification.",
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{64}$"
    }
  },
  "required": [
    "resource",
    "outcome"
  ]
}
```

**Example response**
```json
{
  "recorded": true,
  "verified": true,
  "note": "Payment found on-chain. This report counts toward the score."
}
```