{ "openapi": "3.1.0", "info": { "title": "Teppi", "description": "The record of what happened when someone paid a machine service. Every entry carries the settlement transaction, the hashes of what was sent and returned, and the check that ran.", "version": "0.1.0" }, "servers": [ { "url": "https://api.teppi.xyz" } ], "paths": { "/v1/check": { "get": { "operationId": "checkBeforePaying", "summary": "Returns what the record holds about any x402 endpoint url before you pay it: the grade if one exists, the price and rails its last 402 offered, and what is wrong with the listing. A url never seen is put in line for a free handshake, so ask again in an hour.", "tags": [ "check", "grade", "x402", "url", "before-paying" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri", "minLength": 8, "maxLength": 2048 } }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GET", "POST" ] } }, { "name": "pay_to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$|^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "the payTo address from the 402, to learn what the record knows about who gets paid" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "what the record holds about the url, signed with the check key", "properties": { "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ], "description": "a letter, or UNRATED when not enough is known" }, "tier": { "type": [ "string", "null" ], "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED", null ], "description": "what measured it" }, "composite": { "type": [ "number", "null" ], "description": "the number the letter summarises" }, "why": { "type": "string", "description": "why the grade is what it is, in words" }, "asked": { "type": "string", "description": "the url or id as it was asked" }, "matched": { "type": "string", "enum": [ "exact", "path", "none" ], "description": "how the url met the record: exactly, by path alone, or not at all" }, "defects": { "type": "array", "items": { "type": "object", "properties": { "defect": { "type": "string", "description": "what the listing gets wrong" }, "says": { "type": "string", "description": "the same in words" }, "seenAt": { "type": [ "string", "null" ], "description": "when it was last seen" } }, "required": [ "defect", "says" ] }, "description": "what is wrong with the listing" }, "capabilityId": { "type": "string", "description": "the endpoint in the record, when it is there" }, "url": { "type": "string", "description": "the url the record holds for it" }, "components": { "type": [ "object", "null" ], "description": "every part of the grade, each with its bound and sample count", "properties": { "liveness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "correctness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "honesty": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "schema_conformance": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "latency_p95": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "price_stability": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] } } }, "sampleCount": { "type": "integer", "minimum": 0, "description": "samples behind the grade" }, "computedAt": { "type": [ "string", "null" ], "description": "when the grade was computed" }, "observationsSince": { "type": "integer", "minimum": 0, "description": "observations newer than the grade" }, "withdrawnSince": { "type": "integer", "minimum": 0, "description": "records the grade stood on that a correction withdrew after it was signed; when it equals sampleCount the grade stands on nothing" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "conditions on the grade" }, "observed": { "type": "object", "description": "what the free handshakes saw", "properties": { "probes": { "type": "integer", "minimum": 0, "description": "handshakes" }, "answered": { "type": "integer", "minimum": 0, "description": "handshakes it answered" }, "askedForPayment": { "type": "integer", "minimum": 0, "description": "handshakes answered with a 402" }, "firstSeen": { "type": [ "string", "null" ], "description": "the first handshake" }, "lastSeen": { "type": [ "string", "null" ], "description": "the newest handshake" }, "spanDays": { "type": "number", "description": "days from the first handshake to now" }, "advertised": { "type": [ "object", "null" ], "description": "what its newest 402 asked", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "the price" }, "asset": { "type": "string", "description": "the token" }, "atomic": { "type": [ "string", "null" ], "description": "the same price in the token's smallest unit, as a 402 states it" }, "networks": { "type": "array", "items": { "type": "string" }, "description": "CAIP-2 ids" } } }, "distinctPrices": { "type": "integer", "minimum": 0, "description": "prices seen" }, "protocols": { "type": "array", "items": { "type": "string" }, "description": "x402, mpp" } } }, "reproduce": { "type": [ "string", "null" ], "description": "the command that runs the same handshake without us" }, "scorecard": { "type": [ "string", "null" ], "description": "the signed card behind the grade" }, "corrections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "the correction id" }, "fault": { "type": "string", "description": "which of our own faults it names" }, "says": { "type": "string", "description": "what we got wrong" }, "issuedAt": { "type": "string", "description": "when it was issued" }, "recordId": { "type": [ "string", "null" ], "description": "the one record it names, or null for all of them" }, "gradeAt": { "type": [ "string", "null" ], "description": "the one grade it names, or null" } }, "required": [ "id", "fault", "says", "issuedAt" ] }, "description": "what we got wrong about it" }, "queued": { "type": "boolean", "description": "a url never seen, now in line for a handshake" }, "next": { "type": "string", "description": "what to do next about a url the record has not seen" }, "payee": { "type": [ "object", "null" ], "description": "what the record knows about whoever pay_to names", "properties": { "address": { "type": "string", "description": "the payout address" }, "origins": { "type": "array", "items": { "type": "string" }, "description": "origins that pay it" }, "listed": { "type": "integer", "minimum": 0, "description": "active endpoints behind it" }, "graded": { "type": "integer", "minimum": 0, "description": "of those, holding a letter" }, "bestBand": { "type": [ "string", "null" ], "description": "the best letter behind it" }, "withDefects": { "type": "integer", "minimum": 0, "description": "of those, with a listing defect" } } }, "buy": { "type": "object", "description": "how to buy it through Teppi and be charged only if the answer passes", "properties": { "url": { "type": "string", "description": "where to send the call" }, "method": { "type": "string", "description": "GET or POST" }, "seller_price": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "the seller's price as its own 402 last asked it" }, "fee": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "Teppi's fee on that price" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "an estimate; the via url quotes again off the seller now" }, "asset": { "type": "string", "description": "USDC" }, "guarantee": { "type": "string", "description": "when the buyer is charged" }, "publish": { "type": "string", "description": "the header that puts the call in the record" } } }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "band", "tier", "composite", "why", "asked", "matched", "defects", "answered_at", "signing_key_id", "signature" ] } } } } } } }, "/v1/trust/{id}": { "get": { "operationId": "getGrade", "summary": "Returns the quality grade for a paid endpoint, with the components behind it and a sample of the evidence. Use before paying an endpoint you have not used.", "tags": [ "grade", "quality", "x402", "endpoint" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cap_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "every published card for the endpoint, deepest first", "properties": { "schema": { "type": "string", "description": "teppi.trust.v1" }, "capability_id": { "type": "string", "description": "the endpoint" }, "scorecards": { "type": "array", "items": { "type": "object", "description": "one signed card: a grade with everything needed to recompute it", "properties": { "schema": { "type": "string", "description": "teppi.scorecard.v1 or v2" }, "capability_id": { "type": "string", "description": "the endpoint graded" }, "tier": { "type": "string", "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED" ], "description": "what measured it" }, "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ], "description": "the letter, or UNRATED" }, "composite": { "type": "number", "description": "the weighted sum of the lower bounds" }, "components": { "type": [ "object", "null" ], "description": "every part of the grade, each with its bound and sample count", "properties": { "liveness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "correctness": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "honesty": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "schema_conformance": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "latency_p95": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] }, "price_stability": { "type": "object", "description": "one measured part of the grade", "properties": { "point": { "type": [ "number", "null" ], "description": "what the samples showed" }, "lower": { "type": [ "number", "null" ], "description": "the published lower bound" }, "upper": { "type": [ "number", "null" ], "description": "the upper bound, where one is computed" }, "n_eff": { "type": "number", "minimum": 0, "description": "effective samples behind it" }, "method": { "type": "string", "description": "how the bound was computed" } }, "required": [ "point", "lower", "n_eff", "method" ] } } }, "weights_applied": { "type": "object", "description": "the weight each scored part carried" }, "weights_version": { "type": "string", "description": "which weights" }, "sample_count": { "type": "integer", "minimum": 0, "description": "samples behind it" }, "window_days": { "type": "integer", "minimum": 0, "description": "the window it read" }, "window_start": { "type": "string", "description": "where the window starts" }, "computed_at": { "type": "string", "description": "when it was computed" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "conditions on the grade" }, "evidence_sample": { "type": "array", "items": { "type": "string" }, "description": "the evidence hashes it stood on" }, "method": { "type": "string", "description": "the method page it was computed under" }, "verifier_version": { "type": "string", "description": "which verifier scored the samples" }, "signing_key_id": { "type": "string", "description": "the published key that signed it" }, "canonicalization": { "type": "string", "description": "RFC8785" }, "signature": { "type": "string", "description": "ed25519 over the canonical bytes of the card" } }, "required": [ "schema", "capability_id", "tier", "band", "composite", "components", "signature" ] }, "description": "the cards, deepest tier first" }, "disputes": { "type": "array", "items": { "type": "object" }, "description": "the seller's own receipts" }, "corrections": { "type": "array", "items": { "type": "object" }, "description": "what we got wrong" } }, "required": [ "schema", "capability_id", "scorecards", "disputes", "corrections" ] } } } } } } }, "/v1/trust/index": { "get": { "operationId": "marketIndex", "summary": "One line per listed x402 endpoint: its band, the tier it stands on, its sample count, its defects and its signed card. Use to show the record beside every listing in a catalog.", "tags": [ "index", "catalog", "grade", "ndjson" ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/market/records": { "get": { "operationId": "marketRecords", "summary": "One line per paid call the record holds: what was paid, on which chain and transaction, what came back on each check, whether a correction of ours set it aside, and where its evidence is. Use to recount any figure about the market.", "tags": [ "records", "evidence", "dataset", "ndjson" ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/trust/feed": { "get": { "operationId": "gradeFeed", "summary": "Streams every grade as it is published, newline delimited, resumable from a cursor. Use to mirror the whole record.", "tags": [ "feed", "mirror", "grade", "ndjson" ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/archive": { "get": { "operationId": "archiveFiles", "summary": "Lists every file old handshakes, server looks and free cards were moved to, with the hash each unpacks to. Use to fetch what the database no longer holds.", "tags": [ "archive", "mirror", "history", "grade" ], "parameters": [ { "name": "subject", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "liveness_probes", "mcp_probes", "grades", "mcp_grades" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "every archive file, oldest first, a page at a time", "properties": { "schema": { "type": "string", "description": "teppi.archive.list.v1" }, "kept_in_the_database_for": { "type": "object", "additionalProperties": { "type": "string" }, "description": "how long each table keeps a row before it may move, iso 8601" }, "never_moved": { "type": "array", "items": { "type": "string" }, "description": "what always stays" }, "manifests": { "type": "array", "items": { "type": "object", "description": "one file of old rows moved out of the database, and how to check it", "properties": { "schema": { "type": "string", "description": "teppi.archive.v1" }, "id": { "type": "string", "description": "the manifest" }, "subject": { "type": "string", "enum": [ "liveness_probes", "mcp_probes", "grades", "mcp_grades" ], "description": "the table the rows came from" }, "from": { "type": "string", "description": "the start of the day the rows fall in, iso 8601 utc" }, "to": { "type": "string", "description": "the end of that day, exclusive" }, "rows": { "type": "integer", "minimum": 0, "description": "how many rows the file holds" }, "content_hash": { "type": "string", "description": "sha256 of the file once unpacked" }, "bytes": { "type": "integer", "minimum": 0, "description": "the size of the file as served, packed" }, "verified_at": { "type": "string", "description": "when the file was read back from the store and hashed again" }, "format": { "type": "string", "description": "what a line of the file is" }, "file": { "type": "string", "description": "where the file is served" }, "reproduce": { "type": "string", "description": "the command that fetches it and prints its hash" }, "signing_key_id": { "type": "string", "description": "the published key that signed it, the one that signs scorecards" }, "canonicalization": { "type": "string", "description": "RFC8785" }, "signature": { "type": "string", "description": "ed25519 over the canonical bytes of the manifest" } }, "required": [ "schema", "id", "subject", "from", "to", "rows", "content_hash", "bytes", "file", "signing_key_id", "signature" ], "additionalProperties": false }, "description": "this page of files" }, "next": { "type": [ "string", "null" ], "description": "the next page, or null on the last" } }, "required": [ "schema", "kept_in_the_database_for", "never_moved", "manifests", "next" ], "additionalProperties": false } } } } } } }, "/v1/archive/{id}": { "get": { "operationId": "archiveManifest", "summary": "Returns one archive manifest: the day, the row count, the hash of the unpacked file, and the command that fetches and checks it.", "tags": [ "archive", "history", "reproduce" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^arc_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "one file of old rows moved out of the database, and how to check it", "properties": { "schema": { "type": "string", "description": "teppi.archive.v1" }, "id": { "type": "string", "description": "the manifest" }, "subject": { "type": "string", "enum": [ "liveness_probes", "mcp_probes", "grades", "mcp_grades" ], "description": "the table the rows came from" }, "from": { "type": "string", "description": "the start of the day the rows fall in, iso 8601 utc" }, "to": { "type": "string", "description": "the end of that day, exclusive" }, "rows": { "type": "integer", "minimum": 0, "description": "how many rows the file holds" }, "content_hash": { "type": "string", "description": "sha256 of the file once unpacked" }, "bytes": { "type": "integer", "minimum": 0, "description": "the size of the file as served, packed" }, "verified_at": { "type": "string", "description": "when the file was read back from the store and hashed again" }, "format": { "type": "string", "description": "what a line of the file is" }, "file": { "type": "string", "description": "where the file is served" }, "reproduce": { "type": "string", "description": "the command that fetches it and prints its hash" }, "signing_key_id": { "type": "string", "description": "the published key that signed it, the one that signs scorecards" }, "canonicalization": { "type": "string", "description": "RFC8785" }, "signature": { "type": "string", "description": "ed25519 over the canonical bytes of the manifest" } }, "required": [ "schema", "id", "subject", "from", "to", "rows", "content_hash", "bytes", "file", "signing_key_id", "signature" ], "additionalProperties": false } } } } } } }, "/v1/route/plan": { "post": { "operationId": "planOutcome", "summary": "Turns a goal and a budget into a costed chain of endpoints, before any money is spent. Returns the plan and the estimate.", "tags": [ "plan", "budget", "routing", "estimate" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string" }, "budget_usd": { "type": "string" } }, "required": [ "goal", "budget_usd" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a costed plan, which moves no money", "properties": { "plan_id": { "type": "string", "pattern": "^pln_[0-9A-HJKMNP-TV-Z]{26}$", "description": "the plan" }, "estimated_usd": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the plan is expected to cost" }, "budget_usd": { "type": "string", "description": "the budget asked for" }, "expires_at": { "type": "string", "description": "when the quote stops being buyable" }, "ttl_seconds": { "type": "integer", "minimum": 0, "description": "seconds the quote holds" }, "steps": { "type": "array", "description": "the calls, in order", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "description": "its place in the plan" }, "class": { "type": "string", "description": "what kind of call" }, "capability_id": { "type": "string", "description": "the endpoint picked" }, "grade": { "type": "object", "description": "its grade and what measured it", "properties": { "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED", null ] } } }, "est_usd": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "its expected price" }, "purpose": { "type": "string", "description": "what the step is for" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "endpoints tried instead, no dearer" } }, "required": [ "index", "class", "capability_id", "est_usd" ] } }, "missing": { "type": "array", "description": "what the goal needed that nothing listed could do", "items": { "type": "object", "properties": { "class": { "type": [ "string", "null" ], "description": "the kind of call" }, "reason": { "type": "string", "description": "why it is missing" } } } }, "guarantee": { "type": "string", "description": "when a buyer of the plan is charged" } }, "required": [ "plan_id", "estimated_usd", "expires_at", "steps", "missing", "guarantee" ] } } } } } } }, "/v1/route/execute": { "post": { "operationId": "executePlan", "summary": "Buys every step of a plan from /v1/route/plan with one payment, and settles it only if every answer came back whole and matching the schema its seller published.", "tags": [ "buy", "plan", "pay-on-delivery", "x402" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "pattern": "^pln_[0-9A-HJKMNP-TV-Z]{26}$" }, "inputs": { "type": "object", "description": "Each step's input by its index. {\"$from\": {\"step\": 0, \"pointer\": \"/id\"}} copies a value out of an earlier step's answer." } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "payment required: the seller's price plus the fee, in the body and the payment-required header" }, "424": { "description": "the seller could not be bought or its answer failed its checks, and nothing was charged" } }, "x-teppi-fee": { "basis_points": 1000, "minimum": "0.002000", "asset": "USDC", "on": "the seller's price" } } }, "/v1/evaluate": { "post": { "operationId": "evaluateDelivery", "summary": "Checks an answer you already got from a listed endpoint against the schema its seller published, and signs what the checks found. Free, and nothing is written to the record.", "tags": [ "evaluate", "schema", "delivery", "signed" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capability_id": { "type": "string", "pattern": "^cap_[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "body": { "type": "string", "maxLength": 1000000 } }, "required": [ "capability_id", "status", "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "an answer you hold, judged against its seller's published schema; nothing stored", "properties": { "capability": { "type": "object", "properties": { "id": { "type": "string", "description": "the endpoint" }, "url": { "type": "string", "description": "its url" }, "method": { "type": "string", "description": "GET or POST" } } }, "evaluated": { "type": "object", "description": "the answer judged, by its hash", "properties": { "status": { "type": "integer", "minimum": 0, "description": "its status" }, "body": { "type": "string", "description": "sha256 of its body" } } }, "passed": { "type": "boolean", "description": "whole and matching the schema" }, "checks": { "type": "array", "items": { "type": "object" }, "description": "each check and its result" }, "schema_declared": { "type": "boolean", "description": "the seller published a schema" }, "schema_conformance": { "type": [ "number", "null" ], "description": "share of the schema met" }, "injection_observed": { "type": "boolean", "description": "the body tried to give instructions" }, "honesty": { "type": "null", "description": "not measured: nothing was paid" }, "correctness": { "type": "null", "description": "not measured: nobody holds the right answer" }, "not_measured": { "type": "string", "description": "why" }, "recorded": { "type": "boolean", "const": false, "description": "nothing is written" }, "verifier_version": { "type": "string", "description": "which verifier judged it" }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "capability", "evaluated", "passed", "checks", "answered_at", "signature" ] } } } } } } }, "/v1/exposure": { "post": { "operationId": "fleetExposure", "summary": "Looks up every paid endpoint your agents call at once and adds them up by the address each one pays: which are unknown, which took money and returned nothing, which list what they do not serve, and what that spend is. Free, signed, and a url never seen is put in line for a free handshake.", "tags": [ "exposure", "dependencies", "payout", "signed" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dependencies": { "type": "array", "minItems": 1, "maxItems": 200, "description": "the paid endpoints your agents call, each a url or an object naming one", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "pay_to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$|^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "the payTo address from the 402, to learn what the record knows about who gets paid" }, "calls_per_month": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "how often your fleet calls it, to add up what it costs" } }, "required": [ "url" ], "additionalProperties": false } ] } } }, "required": [ "dependencies" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a fleet's paid dependencies, each looked up as a check is, added up by who gets paid", "properties": { "schema": { "type": "string", "const": "teppi.exposure.v1", "description": "this document" }, "dependencies": { "type": "array", "description": "one line per dependency, in the order asked", "items": { "type": "object", "properties": { "asked": { "type": "string", "description": "the url or id as sent" }, "capability_id": { "type": [ "string", "null" ], "description": "the endpoint the record matched, or null" }, "matched": { "type": "string", "enum": [ "exact", "path", "none" ], "description": "how" }, "standing": { "type": "string", "enum": [ "not_in_record", "took_the_money", "listing_mismatch", "lettered", "paid_no_letter", "handshake_only" ], "description": "what to look at first; not_in_record and handshake_only mean unknown" }, "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ], "description": "the deepest card, UNRATED if none" }, "tier": { "type": [ "string", "null" ], "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED", null ], "description": "what it stands on" }, "sample_count": { "type": "integer", "minimum": 0, "description": "samples behind the card" }, "computed_at": { "type": [ "string", "null" ], "description": "when the card was worked out" }, "paid_calls": { "type": "integer", "minimum": 0, "description": "paid calls the record holds, less any we withdrew" }, "took_the_money": { "type": "integer", "minimum": 0, "description": "of those, settled with nothing back" }, "defects": { "type": "array", "items": { "type": "object", "properties": { "defect": { "type": "string", "description": "what the listing gets wrong" }, "says": { "type": "string", "description": "the same in words" }, "seenAt": { "type": [ "string", "null" ], "description": "when it was last seen" } }, "required": [ "defect", "says" ] }, "description": "what the listing gets wrong before payment" }, "price": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "the listed price" }, "payout": { "type": [ "string", "null" ], "description": "the address it pays, when the 402 or the record names one" }, "pay_to_seen_before": { "type": [ "boolean", "null" ], "description": "the pay_to sent is one this seller was seen paying; null when unknowable" }, "calls_per_month": { "type": [ "integer", "null" ], "minimum": 0, "description": "as sent" }, "monthly_spend": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "price times calls_per_month" }, "card": { "type": [ "string", "null" ], "description": "the signed card" }, "reproduce": { "type": [ "string", "null" ], "description": "the command that reruns the free handshake" } }, "required": [ "asked", "capability_id", "matched", "standing", "band", "tier", "defects" ] } }, "by_payout": { "type": "array", "description": "each address the fleet pays, and everything the record holds behind it", "items": { "type": "object", "properties": { "payout": { "type": "string", "description": "the address" }, "your_dependencies": { "type": "integer", "minimum": 0, "description": "of the dependencies sent, how many pay it" }, "origins": { "type": "integer", "minimum": 0, "description": "origins behind it" }, "listed": { "type": "integer", "minimum": 0, "description": "active endpoints behind it" }, "lettered": { "type": "integer", "minimum": 0, "description": "of those, holding a letter" }, "best_band": { "type": [ "string", "null" ], "description": "the best letter behind it" }, "with_defects": { "type": "integer", "minimum": 0, "description": "of those, with a listing defect" }, "took_the_money": { "type": "integer", "minimum": 0, "description": "of those, with a paid call settled and nothing back" } }, "required": [ "payout", "your_dependencies", "listed", "took_the_money" ] } }, "totals": { "type": "object", "description": "the lines added up; spend counts only lines that sent calls_per_month", "properties": { "dependencies": { "type": "integer", "minimum": 0, "description": "lines" }, "not_in_record": { "type": "integer", "minimum": 0, "description": "unknown to the record" }, "took_the_money": { "type": "integer", "minimum": 0, "description": "settled with nothing back" }, "listing_mismatch": { "type": "integer", "minimum": 0, "description": "a defect before payment" }, "lettered": { "type": "integer", "minimum": 0, "description": "holding a letter" }, "paid_no_letter": { "type": "integer", "minimum": 0, "description": "paid for, too few samples for a letter" }, "handshake_only": { "type": "integer", "minimum": 0, "description": "answers a handshake, never paid for" }, "payouts": { "type": "integer", "minimum": 0, "description": "distinct addresses paid" }, "priced": { "type": "integer", "minimum": 0, "description": "lines with a spend" }, "monthly_spend": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "all of it" }, "monthly_spend_where_the_record_shows_a_failure": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "took the money, a defect, D or F" }, "monthly_spend_not_yet_measured": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "no letter and no failure shown: unknown" } } }, "watch": { "type": "object", "description": "where to be told when a card falls", "properties": { "url": { "type": "string", "description": "the endpoint" }, "says": { "type": "string", "description": "what to post" } } }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "schema", "dependencies", "by_payout", "totals", "answered_at", "signature" ] } } } } } } }, "/v1/policy/payouts": { "get": { "operationId": "policyPayouts", "summary": "Lists payout addresses where at least three paid calls settled and brought back nothing usable, with the lower bound of that share, how many origins each address stands behind, and the evidence. format=cdp or privy returns a rule those wallet policy engines read; format=plain one address a line.", "tags": [ "policy", "wallet", "payout", "signed" ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "plain", "cdp", "privy" ] } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "payout addresses a wallet signing policy can refuse, each with the paid calls that put it on the list", "properties": { "schema": { "type": "string", "const": "teppi.policy.v1", "description": "this document" }, "rule": { "type": "string", "description": "the whole rule, so the same counts give the same list" }, "says": { "type": "string", "description": "what a refusal reaches and what the formats are" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "payout": { "type": "string", "description": "the address" }, "paid": { "type": "integer", "minimum": 0, "description": "our paid calls to it, less any a correction set aside" }, "kept": { "type": "integer", "minimum": 0, "description": "of those, settled with nothing usable back" }, "kept_share": { "type": "number", "minimum": 0, "maximum": 1, "description": "kept over paid" }, "kept_share_low": { "type": "number", "minimum": 0, "maximum": 1, "description": "95% Wilson lower bound" }, "endpoints": { "type": "integer", "minimum": 0, "description": "endpoints behind it that kept a payment" }, "origins": { "type": "integer", "minimum": 0, "description": "origins behind the address, which a refusal reaches" }, "last_kept_at": { "type": [ "string", "null" ], "description": "the latest kept payment" }, "evidence": { "type": "array", "items": { "type": "string" }, "description": "the newest kept calls" }, "seller_page": { "type": "string", "description": "where the record behind the address is shown" } }, "required": [ "payout", "paid", "kept", "kept_share_low", "origins", "evidence" ] } }, "formats": { "type": "object", "properties": { "plain": { "type": "string", "description": "one address a line" }, "cdp": { "type": "string", "description": "rules for the Coinbase CDP policy engine" }, "privy": { "type": "string", "description": "a rule for a Privy policy" } } }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "schema", "rule", "entries", "answered_at", "signature" ] } } } } } } }, "/v1/models": { "get": { "operationId": "modelSellers", "summary": "Lists sellers that name the same model, each with its listed price and card, and how far comparing their answers has got. A seller is named as differing only after three control runs held. Free and signed.", "tags": [ "model", "inference", "resellers", "signed" ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "sellers that name one model, grouped by a person, and what comparing them may say yet", "properties": { "schema": { "type": "string", "const": "teppi.models.v1", "description": "this document" }, "families": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "the model as people call it" }, "status": { "type": "string", "enum": [ "controls_not_run", "controls_failed", "not_compared_yet", "compared" ], "description": "how far the comparison has got" }, "says": { "type": "string", "description": "what the status means" }, "controls": { "type": "object", "properties": { "same_seller_a_week_apart": { "type": [ "string", "null" ], "enum": [ "held", "failed", null ], "description": "null until the run is made" }, "shared_upstream": { "type": [ "string", "null" ], "enum": [ "held", "failed", null ], "description": "null until the run is made" }, "known_different": { "type": [ "string", "null" ], "enum": [ "held", "failed", null ], "description": "null until the run is made" } }, "required": [ "same_seller_a_week_apart", "shared_upstream", "known_different" ] }, "sellers": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "the seller" }, "capability_id": { "type": "string", "description": "its endpoint" }, "model": { "type": "string", "description": "the model as this seller spells it" }, "url": { "type": [ "string", "null" ], "description": "the endpoint url" }, "price": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "the listed price" }, "active": { "type": "boolean", "description": "still listed" }, "band": { "type": "string", "enum": [ "A", "B", "C", "D", "F", "UNRATED" ], "description": "the deepest card" }, "tier": { "type": [ "string", "null" ], "enum": [ "LIVENESS_VERIFIED", "DELIVERY_VERIFIED", "OUTCOME_VERIFIED", null ], "description": "what it stands on" }, "sample_count": { "type": "integer", "minimum": 0, "description": "samples behind the card" } }, "required": [ "label", "capability_id", "model", "band" ] } }, "findings": { "type": "array", "description": "empty until every control held", "items": { "type": "object", "properties": { "capability_id": { "type": "string", "description": "the seller compared" }, "answers": { "type": "integer", "minimum": 0, "description": "answers it gave" }, "distance": { "type": "number", "minimum": 0, "maximum": 1, "description": "total variation from the others" }, "p": { "type": "number", "minimum": 0, "maximum": 1, "description": "seeded permutation test" }, "verdict": { "type": "string", "enum": [ "differs_from_the_others", "not_enough_to_tell" ], "description": "never the same model" } }, "required": [ "capability_id", "answers", "distance", "p", "verdict" ] } } }, "required": [ "name", "status", "controls", "sellers", "findings" ] } }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "schema", "families", "answered_at", "signature" ] } } } } } } }, "/v1/wallets/{address}": { "get": { "operationId": "walletSpend", "summary": "Reads what one Base address sent in USDC over the last days and lists the sellers it paid that the record knows, with what the record holds behind each: a letter, a paid call that took the money, or nothing measured yet. Free, signed, read when asked and kept nowhere.", "tags": [ "wallet", "spend", "payout", "signed" ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "description": "how far back, 30 if absent" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "what one Base address sent in USDC to payouts the record holds for some seller, read off the chain when asked", "properties": { "schema": { "type": "string", "const": "teppi.wallet.v1", "description": "this document" }, "address": { "type": "string", "description": "the address asked about, lower case" }, "network": { "type": "string", "const": "eip155:8453", "description": "only Base is read" }, "asset": { "type": "string", "const": "USDC", "description": "only USDC is read" }, "window_days": { "type": "integer", "minimum": 1, "maximum": 90, "description": "how far back" }, "window_from": { "type": "string", "description": "the start of the window" }, "window_to": { "type": "string", "description": "the end of the window" }, "paid": { "type": "array", "description": "each seller payout the address sent to, most money first", "items": { "type": "object", "properties": { "payout": { "type": "string", "description": "the address paid" }, "payments": { "type": "integer", "minimum": 0, "description": "transfers to it in the window" }, "spent": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "USDC sent to it in the window" }, "first_tx": { "type": "string", "description": "the oldest transfer in the window" }, "last_tx": { "type": "string", "description": "the newest transfer in the window" }, "last_block": { "type": "integer", "minimum": 0, "description": "the block of the newest transfer" }, "standing": { "type": "string", "enum": [ "took_the_money", "lettered", "not_yet_measured" ], "description": "what the record holds about the address paid, not about these transfers; not_yet_measured is unknown, never bad" }, "origins": { "type": "integer", "minimum": 0, "description": "origins behind the address" }, "listed": { "type": "integer", "minimum": 0, "description": "active endpoints behind it" }, "lettered": { "type": "integer", "minimum": 0, "description": "of those, holding a letter" }, "best_band": { "type": [ "string", "null" ], "description": "the best letter behind it" }, "took_the_money": { "type": "integer", "minimum": 0, "description": "endpoints behind it with a paid call settled and nothing back" }, "seller_page": { "type": "string", "description": "where the record behind the address is shown" } }, "required": [ "payout", "payments", "spent", "last_tx", "standing", "listed", "took_the_money" ] } }, "totals": { "type": "object", "description": "the lines added up", "properties": { "sellers": { "type": "integer", "minimum": 0, "description": "distinct seller payouts paid" }, "payments_to_sellers": { "type": "integer", "minimum": 0, "description": "transfers to them" }, "spent_with_sellers": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "all of it" }, "spent_where_the_record_shows_a_failure": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "to addresses behind which a paid call took the money" }, "spent_with_a_letter": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "to addresses holding a letter and no failure" }, "spent_not_yet_measured": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "to addresses with neither: unknown" }, "other_transfers": { "type": "integer", "minimum": 0, "description": "transfers to addresses the record holds for no seller, never listed" }, "other_spent": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what those moved" } } }, "says": { "type": "string", "description": "what this answer covers and what it does not" }, "answered_at": { "type": "string", "description": "when this answer was given" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "schema", "address", "window_days", "paid", "totals", "answered_at", "signature" ] } } } } } } }, "/v1/watchers": { "post": { "operationId": "registerWatcher", "summary": "Registers an https receiver to be posted a signed notice whenever the card of an endpoint it names falls. The receiver is sent a challenge first and must echo it; the token in the answer is shown once and reads or stops the watcher.", "tags": [ "watch", "notice", "webhook", "signed" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https:[/]{2}", "maxLength": 2048 }, "watch": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "capability ids or urls to be told about" } }, "required": [ "url", "watch" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a watcher kept once its receiver echoed the challenge", "properties": { "watcher_id": { "type": "string", "description": "the watcher" }, "token": { "type": "string", "description": "the one way to read or stop it; shown once and never again" }, "url": { "type": "string", "description": "where notices are posted" }, "watching": { "type": "array", "items": { "type": "string" }, "description": "the capability ids it is told about" }, "not_in_record": { "type": "array", "items": { "type": "string" }, "description": "what was named and is not in the record, so nothing will be said about it" }, "since": { "type": "string", "description": "nothing computed before this is news to it" }, "manage": { "type": "string", "description": "where to read it back, with the token as a bearer" }, "stop": { "type": "string", "description": "where to stop it, with the token as a bearer" }, "notices": { "type": "string", "description": "the schema of what is posted: teppi.notice.v1" }, "says": { "type": "string", "description": "what to do with the token" } }, "required": [ "watcher_id", "token", "url", "watching", "not_in_record", "since" ] } } } } } } }, "/v1/watchers/{watcher_id}": { "get": { "operationId": "watcherState", "summary": "Reads a watcher back, with the token from registering as a bearer: what it follows, whether it is active, and the last fifty notices with whether each arrived.", "tags": [ "watch", "notice", "webhook" ], "parameters": [ { "name": "watcher_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wch_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a watcher and the last fifty notices it was sent, with whether each arrived", "properties": { "watcher_id": { "type": "string", "description": "the watcher" }, "url": { "type": "string", "description": "where notices are posted" }, "active": { "type": "boolean", "description": "false once stopped; a stopped watcher stays stopped" }, "created_at": { "type": "string", "description": "when it was registered" }, "watching": { "type": "array", "items": { "type": "string" }, "description": "the capability ids it is told about" }, "notices": { "type": "array", "items": { "type": "object", "properties": { "notice_id": { "type": "string", "description": "the notice" }, "capability_id": { "type": "string", "description": "what it is about" }, "tier": { "type": "string", "description": "the tier that moved" }, "change": { "type": "string", "description": "band_fell, evidence_lapsed, depth_lost, flag_raised or composite_fell" }, "from": { "type": "string", "description": "before" }, "to": { "type": "string", "description": "after" }, "observed_at": { "type": "string", "description": "when the card that moved was worked out" }, "delivered_at": { "type": [ "string", "null" ], "description": "when the receiver took it, or null" }, "attempts": { "type": "integer", "minimum": 0, "description": "tries so far" }, "last_error": { "type": [ "string", "null" ], "description": "what the last failed try met" } }, "required": [ "notice_id", "capability_id", "change", "delivered_at", "attempts" ] } } }, "required": [ "watcher_id", "url", "active", "watching", "notices" ] } } } } } } }, "/v1/watchers/stop": { "post": { "operationId": "stopWatcher", "summary": "Stops a watcher for good, with the token from registering as a bearer. A stopped watcher is sent nothing more and cannot be started again; register a new one instead.", "tags": [ "watch", "webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watcher_id": { "type": "string", "pattern": "^wch_[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "watcher_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "watcher_id": { "type": "string", "description": "the watcher" }, "active": { "type": "boolean", "const": false, "description": "stopped" } }, "required": [ "watcher_id", "active" ] } } } } } } }, "/v1/via/{capability_id}": { "get": { "operationId": "buyOnDelivery", "summary": "Buys one call to a listed GET endpoint for you, with the query you send, and settles your payment only if the answer came back whole and matching its published schema.", "tags": [ "buy", "pay-on-delivery", "receipt", "x402" ], "parameters": [ { "name": "capability_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cap_[0-9A-HJKMNP-TV-Z]{26}$", "description": "The endpoint to buy, by the id the record lists it under." } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "payment required: the seller's price plus the fee, in the body and the payment-required header" }, "424": { "description": "the seller could not be bought or its answer failed its checks, and nothing was charged" } }, "x-teppi-fee": { "basis_points": 1000, "minimum": "0.002000", "asset": "USDC", "on": "the seller's price" } }, "post": { "operationId": "buyOnDeliveryPost", "summary": "Buys one call to a listed POST endpoint for you, with the json body you send, and settles your payment only if the answer came back whole and matching its published schema.", "tags": [ "buy", "pay-on-delivery", "receipt", "x402" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The seller's own request body, as its listing describes it." } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "payment required: the seller's price plus the fee, in the body and the payment-required header" }, "424": { "description": "the seller could not be bought or its answer failed its checks, and nothing was charged" } }, "x-teppi-fee": { "basis_points": 1000, "minimum": "0.002000", "asset": "USDC", "on": "the seller's price" } } }, "/v1/orders/{order_id}": { "get": { "operationId": "orderReceipt", "summary": "Returns the signed receipt for one purchase made on delivery: the quote, both payments with their transactions, the checks the answer met, and commitments to the bytes.", "tags": [ "receipt", "order", "signed", "pay-on-delivery" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "a signed receipt for one purchase made on delivery", "properties": { "schema": { "type": "string", "description": "teppi.order.v1" }, "order_id": { "type": "string", "description": "the order" }, "kind": { "type": "string", "enum": [ "via", "plan", "step" ], "description": "a call, a plan or a step" }, "status": { "type": "string", "description": "open, passed, failed or refused" }, "reason": { "type": [ "string", "null" ], "description": "why it did not pass" }, "capability": { "type": [ "object", "null" ], "description": "the endpoint bought, null on a plan", "properties": { "id": { "type": "string", "description": "the endpoint" }, "url": { "type": "string", "description": "its url" }, "method": { "type": "string", "description": "GET or POST" } } }, "plan": { "type": [ "object", "null" ], "description": "every try at every step, on a plan" }, "part_of": { "type": [ "object", "null" ], "description": "the plan a step belongs to" }, "quote": { "type": "object", "description": "what the buyer was quoted", "properties": { "seller_price": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "the seller's price" }, "fee": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "Teppi's fee" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the buyer signed for" }, "asset": { "type": "string", "description": "USDC" } } }, "buyer": { "type": "string", "description": "the address that bought it" }, "paid": { "type": [ "object", "null" ], "description": "what the buyer paid", "properties": { "receipt_id": { "type": "string", "description": "the receipt" }, "network": { "type": "string", "description": "the chain it settled on, CAIP-2" }, "settled": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "what moved, null until the chain has said" }, "transaction": { "type": [ "string", "null" ], "description": "the transaction" }, "final": { "type": "boolean", "description": "the receipt is closed" } } }, "bought": { "type": [ "object", "null" ], "description": "what Teppi paid the seller", "properties": { "receipt_id": { "type": "string", "description": "the receipt" }, "network": { "type": "string", "description": "the chain it settled on, CAIP-2" }, "settled": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "what moved, null until the chain has said" }, "transaction": { "type": [ "string", "null" ], "description": "the transaction" }, "final": { "type": "boolean", "description": "the receipt is closed" } } }, "request_commitment": { "type": "string", "description": "salted hash of the request" }, "response_commitment": { "type": [ "string", "null" ], "description": "salted hash of the answer" }, "commitment_scheme": { "type": "string", "description": "how to check a commitment with the salt" }, "checks": { "type": [ "array", "null" ], "description": "what the answer was checked against" }, "delivery": { "type": "object", "description": "liveness, schema conformance, honesty" }, "correctness": { "type": "string", "description": "why correctness is not measured on a buyer's own request" }, "published": { "type": "boolean", "description": "the buyer put the call in the record" }, "evidence": { "type": [ "string", "null" ], "description": "the record entry, when published" }, "verifier_version": { "type": [ "string", "null" ], "description": "which verifier checked it" }, "opened_at": { "type": "string", "description": "when it was opened" }, "closed_at": { "type": [ "string", "null" ], "description": "when it closed" }, "issued_at": { "type": "string", "description": "when this receipt was issued" }, "signing_key_id": { "type": [ "string", "null" ], "description": "the published key that signed this answer" }, "canonicalization": { "type": "string", "description": "how the signed bytes were made: RFC8785" }, "signature": { "type": [ "string", "null" ], "description": "ed25519 over the canonical bytes of everything else here" } }, "required": [ "schema", "order_id", "kind", "status", "quote", "buyer", "issued_at", "signature" ] } } } } } } }, "/v1/buyers/{address}/orders": { "get": { "operationId": "buyerOrders", "summary": "Lists every purchase an address made on delivery, with what it was charged and what was not charged, when the request is signed by that address.", "tags": [ "ledger", "orders", "buyer", "pay-on-delivery" ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "description": "one buyer's purchases, answered only to that address's signature", "properties": { "buyer": { "type": "string", "description": "the address" }, "totals": { "type": "object", "properties": { "orders": { "type": "integer", "minimum": 0, "description": "orders" }, "passed": { "type": "integer", "minimum": 0, "description": "passed and charged" }, "not_charged": { "type": "integer", "minimum": 0, "description": "failed and not charged" }, "charged": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what the buyer was charged" }, "covered_for_you": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what Teppi paid sellers for answers that failed" } } }, "page": { "type": "integer", "minimum": 0, "description": "the page" }, "orders": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string", "description": "the order" }, "kind": { "type": "string", "description": "via or plan" }, "status": { "type": "string", "description": "its status" }, "reason": { "type": [ "string", "null" ], "description": "why it did not pass" }, "capability": { "type": [ "object", "null" ], "description": "the endpoint" }, "plan_id": { "type": [ "string", "null" ], "description": "the plan" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "what it was quoted" }, "charged": { "type": [ "string", "null" ], "pattern": "^\\d+\\.\\d{1,6}$", "description": "what was charged" }, "opened_at": { "type": "string", "description": "when it was opened" } } } } }, "required": [ "buyer", "totals", "page", "orders" ] } } } } } } }, "/v1/docs/extract": { "post": { "operationId": "extractDocument", "summary": "Returns structured json extracted from a public pdf or html document url. Use when you have a document link and need typed fields.", "tags": [ "pdf", "extract", "structured-json", "document" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "content_type": { "type": "string" }, "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 0 }, "pages": { "type": [ "integer", "null" ], "minimum": 1 }, "title": { "type": [ "string", "null" ] }, "headings": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1 }, "text": { "type": "string" } }, "required": [ "level", "text" ], "additionalProperties": false } }, "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "text": { "type": "string" } }, "required": [ "href", "text" ], "additionalProperties": false } }, "text": { "type": "string" }, "text_chars": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" } }, "required": [ "url", "content_type", "sha256", "bytes", "pages", "title", "headings", "links", "text", "text_chars", "truncated" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } }, "/v1/companies/lookup": { "post": { "operationId": "lookupCompany", "summary": "Returns legal entities matching a company name or lei, with jurisdiction, status and registered city, as the global lei registry publishes them.", "tags": [ "company", "lei", "legal-entity", "lookup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "source": { "type": "string", "enum": [ "gleif" ] }, "matches": { "type": "array", "items": { "type": "object", "properties": { "lei": { "type": "string", "pattern": "^[A-Z0-9]{20}$" }, "legal_name": { "type": "string" }, "jurisdiction": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "registration_status": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "last_update": { "type": [ "string", "null" ] } }, "required": [ "lei", "legal_name", "jurisdiction", "status", "registration_status", "city", "country", "last_update" ], "additionalProperties": false } } }, "required": [ "query", "source", "matches" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } }, "/v1/web/evidence": { "post": { "operationId": "webEvidence", "summary": "Returns source urls and verbatim quotations for a factual query, where every quote can be found at the url it cites.", "tags": [ "search", "citation", "quote", "evidence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 300 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "source": { "type": "string", "enum": [ "brave" ] }, "searched": { "type": "integer", "minimum": 0 }, "fetched": { "type": "integer", "minimum": 0 }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https:\\/\\/" }, "title": { "type": [ "string", "null" ] }, "quote": { "type": "string", "minLength": 24, "maxLength": 2000 } }, "required": [ "url", "title", "quote" ], "additionalProperties": false } } }, "required": [ "query", "source", "searched", "fetched", "citations" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } }, "/v1/research/brief": { "post": { "operationId": "researchBrief", "summary": "Returns a brief on a factual query made only of verbatim quotes from public pages, each numbered to the url it was taken from.", "tags": [ "research", "brief", "citation", "quote" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 300 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "brief": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "pattern": "^https:\\/\\/" }, "title": { "type": [ "string", "null" ] }, "quote": { "type": "string", "minLength": 24, "maxLength": 2000 } }, "required": [ "url", "title", "quote" ], "additionalProperties": false } } }, "required": [ "query", "brief", "citations" ], "additionalProperties": false } } } }, "402": { "description": "payment required, terms in the body and the payment-required header" } }, "x-x402": { "amount": "0.020000", "asset": "USDC", "scheme": "exact", "networks": [ "eip155:8453" ] } } } } }