{"info":{"description":"Trust scores for AI bots and the wallets they pay. Free without a key (limited per address); send X-Api-Key for a plan. Every check is signed: see /.well-known/keptvow-signer.json.","title":"Keptvow","version":"1.0.0"},"openapi":"3.1.0","paths":{"/v1/agreements":{"post":{"operationId":"openDeal","requestBody":{"content":{"application/json":{"schema":{"properties":{"outcomes":{"description":"the possible outcomes, e.g. [\"delivered\", \"not delivered\"]","type":"array"},"parties":{"description":"[your agent_id, the other bot's]","type":"array"},"secret":{"description":"your bot's secret","type":"string"}},"required":["parties","outcomes","secret"],"type":"object"}}}},"responses":{"201":{"description":"agreement_id"}},"summary":"Open a deal between two bots; both report the outcome when it's done"}},"/v1/agreements/{id}":{"get":{"operationId":"getDeal","parameters":[{"description":"agreement id","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deal"}},"summary":"A deal's state"}},"/v1/agreements/{id}/accept":{"post":{"operationId":"acceptDeal","requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"its id","type":"string"},"secret":{"description":"its secret","type":"string"}},"required":["agent_id","secret"],"type":"object"}}}},"responses":{"200":{"description":"Accepted"}},"summary":"The other bot accepts the deal"}},"/v1/agreements/{id}/report":{"post":{"operationId":"reportDeal","requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"your id","type":"string"},"outcome":{"description":"one of the deal's outcomes","type":"string"},"secret":{"description":"your secret","type":"string"}},"required":["agent_id","outcome","secret"],"type":"object"}}}},"responses":{"200":{"description":"waiting, settled, disagreed, won_by_default or cancelled"}},"summary":"Report the outcome (also counts as accepting)"}},"/v1/alerts":{"get":{"operationId":"getAlerts","parameters":[{"description":"ms timestamp of the last alert you saw","in":"query","name":"since","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alerts"}},"summary":"Alerts so far for your key"}},"/v1/bots":{"get":{"operationId":"searchBots","parameters":[{"description":"name, number or 0x wallet","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"a category: ai-models, search-web-data, crypto-trading, social-media, images-video, audio-voice, writing-content, compute-storage, security-trust, other, no-description","in":"query","name":"kind","required":false,"schema":{"type":"string"}},{"description":"base (default), ethereum, ... or all","in":"query","name":"chain","required":false,"schema":{"type":"string"}},{"description":"excellent, good, fair, caution or unknown: only bots with that rating (excellent comes only from deals settled through Keptvow)","in":"query","name":"rating","required":false,"schema":{"type":"string"}},{"description":"new for newest first","in":"query","name":"sort","required":false,"schema":{"type":"string"}},{"description":"for paging","in":"query","name":"offset","required":false,"schema":{"type":"string"}},{"description":"1-100","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"json (default), md, text or html","in":"query","name":"format","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Matching bots"}},"summary":"Search every rated bot"}},"/v1/bots/{chain}/{number}/listing":{"get":{"operationId":"getListing","parameters":[{"description":"base, ethereum, bnb, ...","in":"path","name":"chain","required":true,"schema":{"type":"string"}},{"description":"the bot's number in the registry","in":"path","name":"number","required":true,"schema":{"type":"string"}},{"description":"false to take it off, true to put it back (default: the opposite of now)","in":"query","name":"listed","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"listed, sign_this, timestamp_ms"}},"summary":"Whether a registry bot is on Keptvow's listing, and the exact text its owner signs to take it off or put it back"},"post":{"operationId":"setListing","requestBody":{"content":{"application/json":{"schema":{"properties":{"listed":{"description":"false to take it off, true to put it back","type":"boolean"},"signature":{"description":"0x personal_sign signature of sign_this","type":"string"},"timestamp_ms":{"description":"from GET on this address","type":"integer"}},"required":["listed","timestamp_ms","signature"],"type":"object"}}}},"responses":{"200":{"description":"Done"}},"summary":"The bot's owner removes it from Keptvow completely (no page, rating or record in checks), or puts it back, signed with the wallet that owns it in the registry (or its payment wallet)"}},"/v1/bots/{chain}/{number}/listing/file":{"post":{"operationId":"checkListingFile","requestBody":{"content":{"application/json":{"schema":{"properties":{},"required":[],"type":"object"}}}},"responses":{"200":{"description":"listed and a message"}},"summary":"Reads the bot's registration file now: \"keptvow\": \"unlisted\" in it takes the bot off the listing, taking the line out puts it back (at most once a minute)"}},"/v1/check":{"get":{"operationId":"checkPayment","parameters":[{"description":"0x wallet you are about to pay (also accepted: wallet, address, to)","in":"query","name":"pay_to","required":true,"schema":{"type":"string"}},{"description":"how much, in US dollars (also accepted: amount)","in":"query","name":"amount_usd","required":false,"schema":{"type":"string"}},{"description":"json (default), md, text or html","in":"query","name":"format","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verdict, advice, evidence and a signed copy"}},"summary":"Before paying a wallet: ok, careful or stop, with the evidence"},"post":{"operationId":"checkPayments","requestBody":{"content":{"application/json":{"schema":{"properties":{"amount_usd":{"description":"optional, the same for each","type":"number"},"pay_to":{"description":"0x wallets","type":"array"}},"required":["pay_to"],"type":"object"}}}},"responses":{"200":{"description":"One check per wallet"}},"summary":"Check up to 25 wallets at once"}},"/v1/credits":{"post":{"operationId":"buyCredits","requestBody":{"content":{"application/json":{"schema":{"properties":{"amount_usd":{"description":"how much credit","type":"number"}},"required":["amount_usd"],"type":"object"}}}},"responses":{"201":{"description":"A key and how to pay"}},"summary":"Pay-as-you-go: prepaid checks, in USDC on Base"}},"/v1/feeds/risky":{"get":{"operationId":"getRiskFeed","parameters":[{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Risk feed"}},"summary":"Wallets Keptvow answers STOP for, and services asking to be paid at a different wallet than they list; a sample free, in full with Watch and Platform keys"}},"/v1/market":{"get":{"operationId":"getMarket","parameters":[{"description":"a paid market pass, or send the X-Api-Key of a paid Market data, Watch or Platform plan","in":"header","name":"X-Market-Token","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Market report"}},"summary":"What AI agents buy: totals, kinds of service and trends, two weeks old (free); today's full report with a pass"}},"/v1/market.csv":{"get":{"operationId":"getMarketCsv","parameters":[{"description":"a paid market pass, or send the X-Api-Key of a paid Market data, Watch or Platform plan","in":"header","name":"X-Market-Token","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV"}},"summary":"Top sellers as CSV (paid access)"}},"/v1/market/kinds":{"get":{"operationId":"listMarketKinds","parameters":[{"description":"a paid market pass, or send the X-Api-Key of a paid Market data, Watch or Platform plan","in":"header","name":"X-Market-Token","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Kinds"}},"summary":"Each kind of service broken down (paid access)"}},"/v1/market/kinds/{slug}":{"get":{"operationId":"getMarketKind","parameters":[{"description":"e.g. ai-models, search-web-data, crypto-trading","in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"description":"a paid market pass, or send the X-Api-Key of a paid Market data, Watch or Platform plan","in":"header","name":"X-Market-Token","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Kind detail"}},"summary":"One kind: share of spending, payments per day, busiest, fastest-growing and new services, prices, what else its buyers buy (paid access)"}},"/v1/market/services":{"get":{"operationId":"listMarketServices","parameters":[{"description":"a paid market pass, or send the X-Api-Key of a paid Market data, Watch or Platform plan","in":"header","name":"X-Market-Token","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Services"}},"summary":"Every paid service bots bought from in 30 days: sales, price, kind, trend (paid access)"}},"/v1/market/services/{id}":{"get":{"operationId":"getMarketService","parameters":[{"description":"service id from the list","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"a paid market pass, or send the X-Api-Key of a paid Market data, Watch or Platform plan","in":"header","name":"X-Market-Token","required":false,"schema":{"type":"string"}},{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service detail"}},"summary":"One service in full: price against its kind, sales per day, buyers, whether it answers, what its buyers also bought (paid access)"}},"/v1/outcomes":{"post":{"operationId":"reportDelivery","requestBody":{"content":{"application/json":{"schema":{"properties":{"delivered":{"description":"true if the paid result arrived","type":"boolean"},"pay_to":{"description":"optional: the wallet paid","type":"string"},"status":{"description":"or: the HTTP status of the paid request","type":"integer"},"tx":{"description":"payment transaction hash","type":"string"}},"required":["tx"],"type":"object"}}}},"responses":{"202":{"description":"Queued for checking"}},"summary":"After paying: did the result arrive? Checked on-chain"}},"/v1/platforms":{"post":{"operationId":"signUpPlatform","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"your company or project","type":"string"},"pay_with":{"description":"card or usdc","type":"string"},"plan":{"description":"watch or platform","type":"string"}},"required":["name"],"type":"object"}}}},"responses":{"201":{"description":"Your key and how to pay"}},"summary":"Get a plan key, paid by card or USDC"}},"/v1/pricing":{"get":{"operationId":"getPricing","parameters":[],"responses":{"200":{"description":"Prices"}},"summary":"Plans and pay-as-you-go prices"}},"/v1/register":{"post":{"operationId":"register","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"optional name","type":"string"}},"required":[],"type":"object"}}}},"responses":{"201":{"description":"agent_id and a secret (shown once)"}},"summary":"Create a free Keptvow identity for a bot"}},"/v1/sellers/me":{"get":{"operationId":"sellerDashboard","parameters":[{"description":"from POST /v1/sellers/sign-in","in":"header","name":"X-Seller-Token","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Seller numbers"}},"summary":"The signed-in seller's payments, buyers, repeat customers and services"}},"/v1/sellers/sign-in":{"post":{"operationId":"sellerSignIn","requestBody":{"content":{"application/json":{"schema":{"properties":{"signature":{"description":"0x personal_sign signature","type":"string"},"signed_at_s":{"description":"unix seconds from the text to sign","type":"integer"},"wallet":{"description":"0x wallet","type":"string"}},"required":["wallet"],"type":"object"}}}},"responses":{"200":{"description":"A seller token, valid 30 days"}},"summary":"A seller signs in with the wallet its service is paid at; send wallet alone first to get the text to sign"}},"/v1/stats":{"get":{"operationId":"getStats","parameters":[],"responses":{"200":{"description":"Counts"}},"summary":"Public traction numbers"}},"/v1/trust/lookup":{"get":{"operationId":"lookupTrust","parameters":[{"description":"erc8004, icp, ...","in":"query","name":"protocol","required":true,"schema":{"type":"string"}},{"description":"its id there","in":"query","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The bot's Keptvow id and profile"}},"summary":"Find a bot by another protocol's id"}},"/v1/trust/{agent_id}":{"get":{"operationId":"getTrust","parameters":[{"description":"bot id","in":"path","name":"agent_id","required":true,"schema":{"type":"string"}},{"description":"json (default), md, text or html","in":"query","name":"format","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trust profile"}},"summary":"A bot's trust profile (a Keptvow id or erc8004:8453:<number>)"}},"/v1/trust/{agent_id}/badge.svg":{"get":{"operationId":"getBadge","parameters":[{"description":"bot id","in":"path","name":"agent_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SVG image"}},"summary":"An embeddable SVG badge with the bot's score and level"}},"/v1/usage":{"get":{"operationId":"getUsage","parameters":[{"description":"your plan key (also accepted as Authorization: Bearer)","in":"header","name":"X-Api-Key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Usage"}},"summary":"What your key has used and owes this month, line by line"}},"/v1/wallets/{wallet}":{"get":{"operationId":"getWallet","parameters":[{"description":"0x address","in":"path","name":"wallet","required":true,"schema":{"type":"string"}},{"description":"json (default), md, text or html","in":"query","name":"format","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet profile"}},"summary":"A seller wallet: payment history, delivery reports, services"}},"/v1/wallets/{wallet}/reply":{"post":{"operationId":"replyAsSeller","requestBody":{"content":{"application/json":{"schema":{"properties":{"review":{"description":"ask a person to review the verdict","type":"boolean"},"signature":{"description":"0x personal_sign signature of sign_this","type":"string"},"signed_at":{"description":"unix seconds from sign_this","type":"integer"},"text":{"description":"up to 500 characters, shown word for word","type":"string"}},"required":["text"],"type":"object"}}}},"responses":{"201":{"description":"Posted"}},"summary":"The wallet's holder answers its page, signed with that wallet; send without signature to get the exact text to sign"}},"/v1/watch":{"post":{"operationId":"watch","requestBody":{"content":{"application/json":{"schema":{"properties":{"targets":{"description":"0x wallets, erc8004:8453:N or Keptvow ids","type":"array"},"webhook_url":{"description":"optional https URL; alerts are signed X-Keptvow-Signature","type":"string"}},"required":["targets"],"type":"object"}}}},"responses":{"200":{"description":"Watching"}},"summary":"Hear when a bot or wallet you depend on changes standing (Watch and Platform plans)"}}},"servers":[{"url":"https://keptvow.com"}]}