{ "openapi": "3.1.0", "info": { "title": "SET paid agent endpoints", "version": "1.0.0", "description": "Two endpoints paid per request over the Machine Payments Protocol (HTTP 402). The Agent Payment Readiness Assessment classifies the capabilities a buyer declares; it verifies nothing independently and never authorizes execution. The AI Visibility Check reads a public page's robots.txt, llms.txt, sitemap and markup, reports what search and AI crawlers may fetch, and scores the page against a published rubric with prioritized findings; a check that fails is not charged. Subject to the SET Terms of Service at https://simpleeasytransactions.com/terms.", "contact": { "url": "https://simpleeasytransactions.com/contact", "email": "support@simpleeasytransactions.com" }, "termsOfService": "https://simpleeasytransactions.com/terms", "x-guidance": "Two $1.00 services for agents. POST /api/agent/ai-visibility with {\"url\":\"example.com\"} reports what search and AI crawlers may fetch from a public page and what the page and site tell them, with a 0-100 score against a published rubric and prioritized fixes; a failed check is not charged. POST /api/agent/readiness with workflow and all ten capabilities returns a payment-readiness assessment. Unpaid requests answer 402 with a Machine Payments Protocol challenge (card or Link through a Stripe Shared Payment Token, or USDC on Base; x402 clients can pay with PAYMENT-SIGNATURE). Send an Idempotency-Key and reuse it on retries to avoid paying twice. Prepaid alternative: Authorization: Bearer ; GET /api/agent/credits lists plans. The same services are MCP tools at POST /api/mcp." }, "servers": [ { "url": "https://simpleeasytransactions.com" } ], "x-service-info": { "categories": [ "payments", "developer-tools" ], "docs": { "homepage": "https://simpleeasytransactions.com", "llms": "https://simpleeasytransactions.com/llms.txt" } }, "paths": { "/api/agent/readiness": { "post": { "operationId": "createAgentReadinessAssessment", "summary": "Return one deterministic, payment-gated agent payment readiness assessment", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-128 characters. A retry with the same key and body returns the paid result without a second charge; the same key with a different body is refused.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$" }, "example": "agent-run-2026-09-28-0001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "workflow", "capabilities" ], "properties": { "workflow": { "type": "object", "additionalProperties": false, "required": [ "name", "intendedUsers", "targetEnvironment" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "intendedUsers": { "type": "string", "enum": [ "humans", "agents", "both" ] }, "targetEnvironment": { "type": "string", "enum": [ "sandbox", "production" ] } } }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "machine_discovery", "payment_challenge_and_receipt", "idempotency", "webhook_verification", "durable_fulfillment", "user_authentication", "wallet_ownership", "onramp_provider_handoff", "delivery_evidence", "recovery_and_reconciliation" ], "properties": { "machine_discovery": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "payment_challenge_and_receipt": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "idempotency": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "webhook_verification": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "durable_fulfillment": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "user_authentication": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "wallet_ownership": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "onramp_provider_handoff": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "delivery_evidence": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } }, "recovery_and_reconciliation": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "implemented", "partial", "missing", "unknown" ] }, "evidence": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 240 } } } } } } } }, "example": { "workflow": { "name": "Agent checkout for a data API", "intendedUsers": "agents", "targetEnvironment": "sandbox" }, "capabilities": { "machine_discovery": { "status": "implemented" }, "payment_challenge_and_receipt": { "status": "implemented" }, "idempotency": { "status": "implemented" }, "webhook_verification": { "status": "implemented" }, "durable_fulfillment": { "status": "partial" }, "user_authentication": { "status": "partial" }, "wallet_ownership": { "status": "partial" }, "onramp_provider_handoff": { "status": "unknown" }, "delivery_evidence": { "status": "unknown" }, "recovery_and_reconciliation": { "status": "unknown" } } } } } }, "x-payment-info": { "offers": [ { "amount": "100", "currency": "usd", "description": "SET Agent Payment Readiness Assessment ($1.00)", "intent": "charge", "method": "stripe" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "1.00" }, "protocols": [ { "mpp": { "method": "stripe", "intent": "charge", "currency": "usd" } }, { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "USDC" } } ] }, "responses": { "200": { "description": "The assessment (application/json), with a Payment-Receipt header on a paid response or Idempotent-Replayed: true on a keyed replay", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid body or Idempotency-Key; no challenge is issued" }, "401": { "description": "An Authorization: Bearer key that is not a valid SET Agent Credits key" }, "402": { "description": "Payment Required: a WWW-Authenticate: Payment challenge" }, "409": { "description": "The Idempotency-Key was already used for a different request" }, "429": { "description": "Rate limited" }, "503": { "description": "Machine payments are not available right now" } }, "security": [ {}, { "agentCredits": [] } ] } }, "/api/agent/ai-visibility": { "post": { "operationId": "createAiVisibilityCheck", "summary": "Audit a public page's search and AI visibility: crawler access, indexing and page signals, a 0-100 rubric score and prioritized findings", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-128 characters. A retry with the same key and body returns the paid result without a second charge; the same key with a different body is refused.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$" }, "example": "agent-run-2026-09-28-0001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "A public page address, e.g. example.com/pricing. Default ports only; IP addresses and internal names are refused." } } }, "example": { "url": "https://example.com/" } } } }, "x-payment-info": { "offers": [ { "amount": "100", "currency": "usd", "description": "SET AI Visibility Check ($1.00)", "intent": "charge", "method": "stripe" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "1.00" }, "protocols": [ { "mpp": { "method": "stripe", "intent": "charge", "currency": "usd" } }, { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "USDC" } } ] }, "responses": { "200": { "description": "The check (application/json), with a Payment-Receipt header on a paid response or Idempotent-Replayed: true on a keyed replay. `report` (checkVersion 2.0.0) holds: checkedUrl, status, robotsTxt, crawlers (15 search and AI crawlers with role, allowed, the deciding robots.txt rule and the vendor's documentation), llmsTxt, page (title, meta description, canonical, robots directives including noindex, nosnippet, max-snippet and noarchive, JSON-LD types and parse errors, Open Graph, lang, h1 count, server-rendered text length), site (redirects, HTTPS, time to first byte, robots.txt Sitemap and Content-Signal lines, sitemap.xml, llms.txt, llms-full.txt), a 0-100 score with its per-item scoring, the rubric and rubricVersion it was scored against, and findings ordered most severe first, each with severity, observed, why and fix. Every signal comes from public fetches of the page and its site; `limits` states what the check cannot see, and the result implies no ranking, traffic or citation outcome.", "content": { "application/json": { "schema": { "type": "object", "required": ["service", "idempotencyKey", "checkedAt", "report", "limits", "artifactHash"], "properties": { "service": { "type": "string" }, "idempotencyKey": { "type": "string" }, "paymentIntent": { "type": "string", "description": "The payment reference, on a paid response" }, "creditsUsage": { "type": "string", "description": "The SET Agent Credits usage id, on a prepaid response" }, "checkedAt": { "type": "string", "format": "date-time" }, "report": { "type": "object", "required": ["checkedUrl", "status", "robotsTxt", "crawlers", "llmsTxt", "page"], "properties": { "checkVersion": { "type": "string", "example": "2.0.0" }, "checkedUrl": { "type": "string", "format": "uri", "description": "The address that answered, after redirects" }, "status": { "type": "integer", "description": "The page's HTTP status" }, "robotsTxt": { "type": "string", "enum": ["found", "missing", "unreachable"] }, "crawlers": { "type": "array", "items": { "type": "object", "required": ["token", "vendor", "purpose", "source", "allowed", "rule"], "properties": { "token": { "type": "string" }, "vendor": { "type": "string" }, "role": { "type": "string", "enum": ["search", "ai-answers", "ai-training"] }, "purpose": { "type": "string", "description": "From the vendor's documentation" }, "source": { "type": "string", "format": "uri", "description": "The vendor's documentation" }, "fallback": { "type": "string", "description": "The token whose robots.txt group this crawler follows when none names it, per its vendor" }, "allowed": { "type": "boolean" }, "rule": { "type": ["string", "null"], "description": "The robots.txt rule that decided it" }, "group": { "type": ["string", "null"], "description": "For a crawler with a fallback, the user-agent group that applied" } } } }, "llmsTxt": { "type": "string", "enum": ["found", "missing"] }, "page": { "type": "object", "properties": { "title": { "type": ["string", "null"] }, "titleLength": { "type": "integer" }, "metaDescription": { "type": ["string", "null"] }, "metaDescriptionLength": { "type": "integer" }, "canonical": { "type": ["string", "null"] }, "canonicalCount": { "type": "integer" }, "canonicalIsSelf": { "type": "boolean" }, "noindexMeta": { "type": "boolean" }, "noindexHeader": { "type": "boolean" }, "robots": { "type": "object", "description": "meta, header, nosnippet, maxSnippet (-1 for no limit), noarchive, nocache, noai, noimageai" }, "jsonLd": { "type": "object", "description": "blocks, invalid, types and keyTypes (Organization, WebSite, FAQPage, Article, Product, Service)" }, "openGraph": { "type": "object", "description": "Whether og:title, og:description, og:image, og:url and og:type are present" }, "lang": { "type": ["string", "null"] }, "h1Count": { "type": "integer" }, "textLength": { "type": "integer", "description": "Characters of body text in the HTML as served, outside script, style, noscript, template and svg" }, "wordCount": { "type": "integer" }, "truncated": { "type": "boolean", "description": "The page exceeded 512 KB and only its start was read" } } }, "site": { "type": "object", "properties": { "requestedUrl": { "type": "string" }, "redirects": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "integer" } } } }, "https": { "type": "object", "properties": { "finalUrlHttps": { "type": "boolean" }, "httpRedirectsToHttps": { "type": ["boolean", "null"] } } }, "ttfbMs": { "type": "integer", "description": "Milliseconds to the page's response headers in this one fetch from SET's server" }, "robotsTxt": { "type": "object", "properties": { "state": { "type": "string" }, "status": { "type": ["integer", "null"] }, "sitemaps": { "type": "array", "items": { "type": "string" } }, "contentSignals": { "type": "array", "items": { "type": "string" } } } }, "sitemapXml": { "type": "object", "properties": { "status": { "type": ["integer", "null"] }, "isSitemap": { "type": "boolean" } } }, "llmsTxt": { "type": "string", "enum": ["found", "missing"] }, "llmsFullTxt": { "type": "string", "enum": ["found", "missing"] } } }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "scoreMax": { "type": "integer", "const": 100 }, "rubricVersion": { "type": "string" }, "rubric": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "points": { "type": "integer" }, "criterion": { "type": "string" } } } }, "scoring": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "points": { "type": "integer" }, "earned": { "type": "integer" } } } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": ["critical", "high", "medium", "low", "info"] }, "rubric": { "type": ["string", "null"], "description": "The rubric item it costs points on, if any" }, "pointsLost": { "type": "integer" }, "observed": { "type": "string" }, "why": { "type": "string" }, "fix": { "type": "string" } } } } } }, "limits": { "type": "array", "items": { "type": "string" } }, "artifactHash": { "type": "string" } } } } } }, "400": { "description": "Invalid body, address or Idempotency-Key; no challenge is issued" }, "401": { "description": "An Authorization: Bearer key that is not a valid SET Agent Credits key" }, "402": { "description": "Payment Required: a WWW-Authenticate: Payment challenge" }, "409": { "description": "The Idempotency-Key was already used for a different request" }, "422": { "description": "The site could not be checked; nothing was charged" }, "429": { "description": "Rate limited" }, "503": { "description": "Machine payments are not available right now" } }, "security": [ {}, { "agentCredits": [] } ] } }, "/api/agent/credits": { "get": { "operationId": "agentCredits", "summary": "SET Agent Credits: the prepaid plans (free), or with a Bearer key the calls left on it", "security": [], "responses": { "200": { "description": "Plans and purchase links, or the balance for the key", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The Bearer key is not valid" } }, "description": "Public. Lists the plans without a key; with Authorization: Bearer it returns that key’s balance (the key is checked by the route, not required)." } } }, "components": { "securitySchemes": { "agentCredits": { "type": "http", "scheme": "bearer", "description": "Optional prepaid SET Agent Credits key (setk_live_...). One fulfilled request spends one call; without it the request is paid over the Machine Payments Protocol." } } } }