{"openapi":"3.1.0","info":{"title":"Kortex API","version":"0.1.0","description":"Kortex tells an agent which x402 service actually works, from evidence: uptime measured over time, a valid 402, and settlements proven on-chain.\n\nEvery payment you make is a bet on a stranger. There is nothing between you and a URL that takes your money and returns nothing.\nDirectories tell you what exists. Measured across 1,015 listed x402 services, only 25% answer with a payment requirement at all.\nA service can claim anything in its own description. It cannot fake having been paid, by other wallets, on-chain.\nAsk Kortex before you pay, and report what happened after. Reporting is free, and only counts when the payment is found on-chain."},"servers":[{"url":"https://kortex.rohnelt.dev"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token from identity.create."}}},"paths":{"/v1/capabilities":{"get":{"operationId":"capabilities","summary":"Describe Kortex","description":"Return the full machine-readable manifest of Kortex: every operation, its price in USD, its input schema and how to pay. Free.\n\nWhen to use: Call this first if you have never used Kortex and want to know what it can do and what it costs.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"service":"Kortex","operations":["resolve","check","report"]}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[]}},"/v1/identity":{"post":{"operationId":"identity_create","summary":"Claim an identity","description":"Turn a wallet address into a permanent Kortex identity and an API token. Free, and grants a small trial credit.\n\nWhen to use: Call this once, before anything else. You need the returned token for every other call. No account, no email, no human.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["identity"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"handle":"swift-heron-4f2a","token":"ktx_sk_...","balance_usd":"0.020000"}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$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"]}}}}}},"/v1/whoami":{"get":{"operationId":"whoami","summary":"Who am I","description":"Your handle, wallet, balance and usage. Free.\n\nWhen to use: Call this to check your balance before a run, or to confirm your token still works.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["identity"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"handle":"swift-heron-4f2a","balance_usd":"0.870000","trial":false}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[]}},"/v1/credit/deposit":{"post":{"operationId":"credit_deposit","summary":"Top up balance","description":"Buy Kortex credit with USDC on Base over x402. One on-chain settlement, then every call is debited off-chain.\n\nWhen to use: Call when your balance is low. Operations cost fractions of a cent, so a single deposit covers hundreds of them.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["billing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"credited_usd":"1.000000","balance_usd":"1.020000","tx":"0x..."}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$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"}}}}}}}},"/v1/resolve":{"get":{"operationId":"resolve","summary":"Find a service that actually works","description":"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.\n\nWhen 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.\n\nPrice: US$0.005000 per call, debited from your prepaid balance.","tags":["discovery","trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"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"}}]}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"need","in":"query","required":true,"description":"What you want done, in plain language. Example: scrape a web page and return clean text.","schema":{"type":"string","minLength":3,"maxLength":200,"description":"What you want done, in plain language. Example: scrape a web page and return clean text."}},{"name":"limit","in":"query","required":false,"description":"How many candidates to return.","schema":{"default":5,"description":"How many candidates to return.","type":"integer","minimum":1,"maximum":20}},{"name":"max_price_usd","in":"query","required":false,"description":"Skip anything that quotes more than this per call.","schema":{"description":"Skip anything that quotes more than this per call.","type":"string"}},{"name":"require_paid","in":"query","required":false,"description":"Only return services with at least one on-chain settlement. Turn off to see untested ones too.","schema":{"default":true,"description":"Only return services with at least one on-chain settlement. Turn off to see untested ones too.","type":"boolean"}}]}},"/v1/check":{"get":{"operationId":"check","summary":"Is this one safe to pay","description":"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.\n\nWhen 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.\n\nPrice: US$0.002000 per call, debited from your prepaid balance.","tags":["trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"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"}}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"resource","in":"query","required":true,"description":"The exact URL you are about to pay, including the path.","schema":{"type":"string","maxLength":2048,"format":"uri","description":"The exact URL you are about to pay, including the path."}},{"name":"probe_now","in":"query","required":false,"description":"Hit the endpoint live instead of using the most recent scheduled probe.","schema":{"default":false,"description":"Hit the endpoint live instead of using the most recent scheduled probe.","type":"boolean"}}]}},"/v1/compare":{"post":{"operationId":"compare","summary":"Rank several candidates","description":"Score two or more resource URLs side by side on the same evidence, and say which one to pay.\n\nWhen to use: Call this when you already have a shortlist and need to pick. Cheaper than calling check once per URL.\n\nPrice: US$0.003000 per call, debited from your prepaid balance.","tags":["trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"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"}]}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$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"]}}}}}},"/v1/history":{"get":{"operationId":"history","summary":"Show me the record","description":"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.\n\nWhen 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.\n\nPrice: US$0.002000 per call, debited from your prepaid balance.","tags":["trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"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"}}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"resource","in":"query","required":true,"description":"The exact URL you are about to pay, including the path.","schema":{"type":"string","maxLength":2048,"format":"uri","description":"The exact URL you are about to pay, including the path."}},{"name":"days","in":"query","required":false,"description":"How far back to look.","schema":{"default":30,"description":"How far back to look.","type":"integer","minimum":1,"maximum":90}}]}},"/v1/watch":{"post":{"operationId":"watch","summary":"Tell me if it changes","description":"Register interest in a service. Kortex records a watch and reports what has changed — price, payout address, or availability — the next time you ask.\n\nWhen 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.\n\nPrice: US$0.005000 per call, debited from your prepaid balance.","tags":["trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"watching":"https://example.com/v1/scrape","watch_id":"wch_01H..."}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$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"]}}}}}},"/v1/report":{"post":{"operationId":"report","summary":"Report what happened","description":"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.\n\nWhen 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.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"recorded":true,"verified":true,"note":"Payment found on-chain. This report counts toward the score."}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$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"]}}}}}}}}