{ "openapi": "3.1.0", "info": { "title": "First Dollar Test", "version": "2026-09-17-v1", "description": "Agent-initiated paid deterministic evaluation. Read live terms before buying. A pass creates a 1 USDC reward obligation; receipt confirmation is separate. This weekend service records discovery evidence. It does not establish general agent profitability or autonomous discovery from a payment alone." }, "servers": [ { "url": "https://api.first-dollar-test.com", "description": "Rendered by npm run build; local by default. Use the published API base for hosted testnet." } ], "paths": { "/v1/opportunity": { "get": { "operationId": "readOpportunity", "summary": "Read current terms without paying", "description": "Free. Decide whether to proceed. A later create call fixes the accepted terms version. A view with no following call is not a recorded decline.", "responses": { "200": { "description": "Current terms, supported chain and wallet requirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Opportunity" } } } } } } }, "/v1/runs": { "post": { "operationId": "createRun", "summary": "Create an unpaid run with a client-owned capability", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Generate and persist before the first call. Reuse unchanged after a lost response. A different body with the same key conflicts.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientToken", "termsVersion" ], "additionalProperties": false, "properties": { "clientToken": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "32 cryptographically random bytes encoded as 64 hex characters without 0x. Save locally before sending; server retains its hash." }, "termsVersion": { "type": "string", "description": "Exact version returned by readOpportunity." }, "discovery": { "$ref": "#/components/schemas/DiscoveryInput" } } } } } }, "responses": { "200": { "description": "Original create result recovered with the same key, capability and body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "201": { "description": "Unpaid run created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid JSON, terms, or bounded request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid client-owned run capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or incompatible run/payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds application size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrollment disabled or safe admission unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enroll": { "post": { "operationId": "enroll", "summary": "Pay the fixed evaluation fee with x402", "security": [ { "runCapability": [] } ], "description": "First call without PAYMENT-SIGNATURE obtains a 402 offer. Sign the exact v2 EVM requirements with the agent wallet and resend the same runId and capability. 202 is an unresolved original payment, not an invitation to pay again. Poll that run; never create another authorization while its payment is settling or unknown.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Base64-encoded x402 v2 PaymentPayload. Do not log or publish the signed authorization.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "runId" ], "additionalProperties": false, "properties": { "runId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Fee confirmed or original paid run recovered; challenge available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "202": { "description": "Original fee settlement pending or unknown. Keep the same run and poll status.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Suggested seconds before polling; event-driven recovery may take longer." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid JSON, terms, or bounded request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid client-owned run capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Fee offer; no challenge until payment confirmation", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded x402 PaymentRequired response" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "404": { "description": "Run or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or incompatible run/payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds application size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrollment disabled or safe admission unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/runs/{id}": { "get": { "operationId": "getRun", "summary": "Poll payment, challenge, verdict and reward independently", "security": [ { "runCapability": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current durable run status; challenge only after fee confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid JSON, terms, or bounded request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid client-owned run capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or incompatible run/payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds application size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrollment disabled or safe admission unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/runs/{id}/submission": { "post": { "operationId": "submitAnswer", "summary": "Submit one bounded JSON transformation answer", "security": [ { "runCapability": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Generate and persist before the first call. Reuse unchanged after a lost response. A different body with the same key conflicts.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "description": "Only a paid, active run can submit. Keep the same answer and idempotency key on a retry. A pass creates one reward obligation atomically; it does not mean the transfer has confirmed. Invalid schema or a failed test does not earn a reward.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answer" ], "additionalProperties": false, "properties": { "answer": { "$ref": "#/components/schemas/ChallengeAnswer" } } } } } }, "responses": { "200": { "description": "Verdict and independent reward status, including original retry result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionResponse" } } } }, "400": { "description": "Invalid JSON, terms, or bounded request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid client-owned run capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or incompatible run/payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds application size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrollment disabled or safe admission unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/runs/{id}/receipt": { "get": { "operationId": "getReceipt", "summary": "Read a machine receipt, including pending reward state", "security": [ { "runCapability": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Fee, verdict and reward are separate. Only a finalized reward transaction verifies payout. Receipt is private to this capability; no automatic public proof page is created.", "responses": { "200": { "description": "Machine receipt; may report pending payment or transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Invalid JSON, terms, or bounded request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid client-owned run capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or incompatible run/payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds application size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrollment disabled or safe admission unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events": { "post": { "operationId": "recordDiscoveryEvent", "summary": "Optionally report discovery or explicit decline evidence", "security": [ {}, { "runCapability": [] } ], "description": "Optional and not required for purchase. Authorization is required when runId is supplied. Self-reported discovery mode and channels are not verified autonomy. Missing referrer stays unknown; cached/shared URLs and human handoff cannot be inferred to be direct autonomous discovery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "runId": { "type": "string" }, "entryChannel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "selfReportedChannel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "mode": { "type": "string", "enum": [ "autonomous", "human_handoff", "unknown" ] }, "evidence": { "type": "string", "enum": [ "server_observed", "self_report", "trace", "unknown" ] }, "declineReason": { "type": "string", "maxLength": 300 } } } } } }, "responses": { "200": { "description": "Evidence recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Evidence recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Evidence accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid JSON, terms, or bounded request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid client-owned run capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or incompatible run/payment state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds application size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrollment disabled or safe admission unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/onchain/{source}": { "post": { "operationId": "receiveOnchainNotification", "summary": "Receive a signed onchain notification from the configured provider", "description": "Operational provider endpoint, not an Agent action. Disabled without webhook configuration. The source signature authenticates the raw body. HTTP 200 follows atomic persistence of the observation and outbox wake; duplicates return 200. Notifications wake independent canonical/finalized RPC verification and do not prove payment completion.", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "cdp", "local" ] } }, { "name": "X-Hook0-Signature", "in": "header", "required": false, "description": "Required for source=cdp; verification uses the configured provider signing secret. Local fixtures use X-Local-Webhook-Signature.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Observation and wake durably stored, or same observation already stored" }, "400": { "description": "Unsupported payload, chain or token" }, "401": { "description": "Missing, invalid or expired source signature" }, "404": { "description": "Notifications disabled" }, "413": { "description": "Body exceeds 32 KB" }, "503": { "description": "Authentication or durable persistence unavailable; resend the same observation" } } } } }, "components": { "securitySchemes": { "runCapability": { "type": "http", "scheme": "bearer", "description": "The clientToken saved before createRun. Never put it in a URL, public proof, analytics or trace." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "DiscoveryChannel": { "type": "string", "enum": [ "google", "mcp_registry", "a2a", "x402_discovery", "direct_url", "human_handoff", "unknown" ] }, "DiscoveryInput": { "type": "object", "description": "Optional claims; the server assigns source evidence separately. Supplied touches are self-reported, not independently verified.", "additionalProperties": false, "properties": { "entryChannel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "selfReportedChannel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "mode": { "type": "string", "enum": [ "autonomous", "human_handoff", "unknown" ] }, "evidence": { "type": "string", "enum": [ "server_observed", "self_report", "trace", "unknown" ] }, "touches": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "channel", "at" ], "properties": { "channel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "at": { "type": "integer", "description": "Unix epoch milliseconds" } }, "additionalProperties": false } } } }, "Discovery": { "type": "object", "required": [ "entryChannel", "mode", "evidence", "touches" ], "properties": { "entryChannel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "selfReportedChannel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "mode": { "type": "string", "enum": [ "autonomous", "human_handoff", "unknown" ] }, "evidence": { "type": "string", "enum": [ "server_observed", "self_report", "trace", "unknown" ] }, "touches": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "channel", "at" ], "properties": { "channel": { "$ref": "#/components/schemas/DiscoveryChannel" }, "at": { "type": "integer", "description": "Unix epoch milliseconds" } } } } }, "additionalProperties": true }, "Terms": { "type": "object", "required": [ "version", "network", "asset", "payTo", "feeUnits", "rewardUnits", "taskVersion", "taskSeconds", "maxAttempts" ], "properties": { "version": { "type": "string" }, "network": { "type": "string", "description": "CAIP-2 EVM network, e.g. eip155:84532" }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "feeUnits": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC 6-decimal integer units. Read the live value, not a documentation example." }, "rewardUnits": { "type": "string", "const": "1000000" }, "taskVersion": { "type": "string" }, "taskSeconds": { "type": "integer", "maximum": 3600 }, "maxAttempts": { "type": "integer" } }, "additionalProperties": true }, "Opportunity": { "type": "object", "required": [ "terms" ], "properties": { "name": { "type": "string" }, "terms": { "$ref": "#/components/schemas/Terms" }, "discoveryChannels": { "type": "object", "description": "Each channel maps to its current availability/indexing status; labels do not enable protocols.", "additionalProperties": { "type": "string" } }, "flow": { "type": [ "object", "array", "string" ] } }, "additionalProperties": true }, "Challenge": { "type": "object", "required": [ "version", "nonce", "instructions", "rows" ], "properties": { "version": { "type": "string" }, "nonce": { "type": "string" }, "instructions": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "id", "category", "quantity", "unitMinor" ], "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "quantity": { "type": "integer" }, "unitMinor": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": true }, "ChallengeAnswer": { "type": "object", "required": [ "nonce", "totals", "grandTotalMinor" ], "properties": { "nonce": { "type": "string" }, "totals": { "type": "array", "items": { "type": "object", "required": [ "category", "totalMinor" ], "properties": { "category": { "type": "string" }, "totalMinor": { "type": "integer" } }, "additionalProperties": false } }, "grandTotalMinor": { "type": "integer" } }, "additionalProperties": false }, "Verdict": { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "string", "enum": [ "pass", "fail" ] }, "code": { "type": "string" }, "failureStep": { "type": "string" } } }, "MoneyStatus": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" }, "amountUnits": { "type": "string" }, "transaction": { "type": "string" } }, "additionalProperties": true }, "SubmissionResponse": { "type": "object", "required": [ "verdict", "run" ], "properties": { "verdict": { "$ref": "#/components/schemas/Verdict" }, "run": { "$ref": "#/components/schemas/Run" } }, "additionalProperties": false }, "Run": { "type": "object", "required": [ "id", "terms", "payment", "reward" ], "properties": { "id": { "type": "string" }, "terms": { "$ref": "#/components/schemas/Terms" }, "payment": { "$ref": "#/components/schemas/MoneyStatus" }, "challenge": { "$ref": "#/components/schemas/Challenge" }, "verdict": { "$ref": "#/components/schemas/Verdict" }, "reward": { "$ref": "#/components/schemas/MoneyStatus" }, "discovery": { "$ref": "#/components/schemas/Discovery" }, "statusUrl": { "type": "string" } }, "additionalProperties": true }, "Receipt": { "type": "object", "properties": { "id": { "type": "string" }, "terms": { "$ref": "#/components/schemas/Terms" }, "fee": { "$ref": "#/components/schemas/MoneyStatus" }, "payment": { "$ref": "#/components/schemas/MoneyStatus" }, "taskVersion": { "type": "string" }, "verifierVersion": { "type": "string" }, "verdict": { "$ref": "#/components/schemas/Verdict" }, "reward": { "$ref": "#/components/schemas/MoneyStatus" }, "refund": { "$ref": "#/components/schemas/MoneyStatus" } }, "additionalProperties": true }, "PaymentRequired": { "type": "object", "properties": { "x402Version": { "type": "integer", "const": 2 }, "accepts": { "type": "array", "items": { "type": "object", "required": [ "scheme", "network", "asset", "amount", "payTo" ], "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "resource": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }