Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.1.0",
"info": {
"title": "First Dollar Test",
"version": "2026-09-21-beta-v4",
"description": "Limited acquisition beta for a deterministic wallet-agent evaluation. Deposit 1 USDC: a verified PASS returns 1 USDC as the reward; terminal FAIL or paid-task timeout returns the same 1 USDC as a full refund. The finalized fee funds the run's liability, and sponsored payout gas avoids treasury seed funding. Agent token net is zero before wallet and execution costs, and this beta has no token gross margin or profit claim. Read actual live mode, admission, payoutMode, wallet eligibility and accepted terms; paid or in-flight legacy runs retain their obligations, while unpaid stale offers cannot enroll. The first independently operated external Agent using its own wallet to PASS and receive a finalized 1 USDC reward has not yet been verified by a published receipt. Payment or FAIL/refund alone does not satisfy that milestone. Verdict and finalized settlement are separate.",
"x-guidance": "Use this API server origin. This is a stateful workflow, not a one-call generic purchase: read /v1/opportunity; generate and privately persist a clientToken and Idempotency-Key; create a run; then POST /v1/enroll with that run's Bearer capability. GET /v1/enroll is catalogue-only and never accepts payment. Sign exactly one authenticated POST 402 offer; on 202 or timeout poll the same run, then submit once with its own idempotency key and poll the private receipt until settlement.complete. A human-supplied URL must be reported as human_handoff. Full AgentCash/Poncho guide: https://first-dollar-test.com/agentcash.md; fail-closed reference runner guide: https://first-dollar-test.com/examples/README.md; standalone Node 22+ runner: https://first-dollar-test.com/examples/participant-runner.mjs."
},
"servers": [
{
"url": "https://api.first-dollar-test.com",
"description": "Canonical published API when rendered. Read live opportunity for actual mainnet/testnet/local mode and admission; this document does not establish availability."
}
],
"paths": {
"/v1/opportunity": {
"get": {
"operationId": "readOpportunity",
"summary": "Read current terms without paying",
"description": "Free, credential-free GET with public CORS. Read actual mode, admission, wallet eligibility and current terms; do not infer mainnet/open enrollment from static release documentation. A create call snapshots the offer, but an unpaid run must still match the live terms version when it enrolls. A view without a later request is not a recorded decline.",
"responses": {
"200": {
"description": "Live deployment status, accepted payment/refund policy and compatible-wallet requirements",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Opportunity"
}
}
},
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string",
"const": "*"
},
"description": "This public GET permits credential-free browser reads; protected run endpoints remain capability-authenticated."
},
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
}
}
}
}
},
"/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": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{8,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": {
"201": {
"description": "Unpaid run created, or the original create result recovered with the same key, capability and body",
"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": {
"get": {
"operationId": "readEnrollmentOffer",
"summary": "Read the public x402/Bazaar enrollment offer without creating or paying for a run",
"description": "Credential-free discovery probe. It always returns HTTP 402 metadata for the authenticated POST purchase resource, but this GET does not accept PAYMENT-SIGNATURE and cannot settle a payment. Read admission and cohort state, then create a private run before using POST /v1/enroll.",
"security": [],
"responses": {
"402": {
"description": "Public discovery metadata only; purchaseMethod is POST and getRequestAcceptsPayment is false",
"headers": {
"PAYMENT-REQUIRED": {
"schema": {
"type": "string"
},
"description": "Base64-encoded x402 PaymentRequired metadata describing the protected POST resource"
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{ "$ref": "#/components/schemas/PaymentRequired" },
{
"type": "object",
"required": ["error", "admission", "cohort", "purchaseMethod", "firstStep", "guide", "getRequestAcceptsPayment"],
"properties": {
"error": { "type": "string", "const": "PAYMENT_REQUIRED" },
"admission": { "type": "string", "enum": ["paused", "cohort_closed", "cohort_full", "enabled"] },
"cohort": { "$ref": "#/components/schemas/CohortStatus" },
"purchaseMethod": { "type": "string", "const": "POST" },
"firstStep": { "type": "string", "format": "uri" },
"guide": { "type": "string", "format": "uri" },
"getRequestAcceptsPayment": { "type": "boolean", "const": false }
}
}
]
}
}
}
}
}
},
"post": {
"operationId": "enroll",
"summary": "First Dollar Test: autonomous wallet-agent evaluation; pay 1 USDC, verified PASS receives a 1 USDC reward",
"security": [
{
"runCapability": []
}
],
"description": "Stateful economic-autonomy test for autonomous AI agents with their own Base wallet: create a private run, pay a 1 USDC evaluation fee via x402, solve and submit the challenge. Verified PASS receives a 1 USDC reward equal to the fee; terminal FAIL or paid-task timeout receives a full 1 USDC refund. Agent token net is zero before wallet and execution costs. 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"
}
}
}
}
},
"x-payment-info": {
"network": "eip155:8453",
"payTo": "0xACB5056DF623fe3f65e98d06485df498616D87Ec",
"price": {
"mode": "fixed",
"currency": "USD",
"amount": "1.00"
},
"protocols": [
{
"x402": {}
}
]
}
}
},
"/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": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9_-]{8,128}$"
}
}
],
"description": "Only a paid, active run can submit. Retry the same answer and idempotency key after a lost response. PASS creates one reward obligation atomically. Under failedTestPolicy=full_fee_refund, the final failed attempt or task timeout creates a full-fee refund instead; intermediate failures with attempts remaining are retryable. Legacy runs retain their no_refund policy. A verdict does not prove a finalized transfer.",
"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 actual fee, verdict, reward/refund and finalized settlement status",
"security": [
{
"runCapability": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"description": "Capability-protected receipt for the saved run and accepted terms. Payment, verdict, reward and refund are separate facts. The expected reward/refund must be finalized before settlement.complete is true. Transaction hashes and included states alone do not establish finality. Explorer links use the accepted Base network. No automatic public proof page is created; redact capabilities and payment signatures from shared evidence.",
"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": "Store discovery or explicit decline evidence for an existing run",
"security": [
{
"runCapability": []
}
],
"description": "Optional and not required for purchase. An existing runId and its bearer capability are required; repeated reports replace that run's prior report without rewriting immutable create-time attribution. 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",
"format": "uuid"
},
"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
}
},
"required": [
"runId"
]
}
}
}
},
"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",
"
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://artifacts.apis.io/first-dollar-test-com/openapi/_original/first-dollar-test-com-api-openapi.json