{ "components": { "headers": { "PAYMENT-REQUIRED": { "description": "The 402 challenge, base64-encoded PaymentRequired. The same document as the response body; a v2 client reads this.", "schema": { "format": "byte", "type": "string" } }, "PAYMENT-RESPONSE": { "description": "Base64-encoded Settlement for the payment that bought this response. The v2 name; sent on every route that takes a payment.", "schema": { "format": "byte", "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying, when the refusal is temporary.", "schema": { "type": "integer" } }, "WWW-Authenticate": { "description": "Sent with a 401: the bearer scheme and the error code, RFC 6750 style.", "schema": { "type": "string" } }, "X-Payment-Response": { "description": "The v1 name for PAYMENT-RESPONSE, carrying the same value, sent for clients written against v1.", "schema": { "format": "byte", "type": "string" } }, "X-Qmarket-Access": { "description": "Why the read was allowed: free, owned or paid.", "schema": { "enum": [ "free", "owned", "paid" ], "type": "string" } }, "X-Qmarket-Price-Cents": { "description": "What this read actually charged, which on a first read is the trial price.", "schema": { "type": "integer" } } }, "parameters": { "after": { "description": "Page cursor: the next_cursor of the previous page. Omit for the first page.", "in": "query", "name": "after", "schema": { "type": "string" } }, "limit": { "description": "Page size. Defaults to 50; clamped to 1–200; non-numeric values are ignored.", "in": "query", "name": "limit", "schema": { "type": "integer" } }, "paymentSignature": { "description": "The signed payment, base64-encoded PaymentPayload. The v2 name for X-PAYMENT; either header is read, and the version is taken from the payload rather than the header it arrived in. Present: settle on the wallet rail. Absent: quote a 402.", "example": "eyJhY2NlcHRlZCI6eyJhbW91bnQiOiI1MDAwMDAwIiwiYXNzZXQiOiIweDgzMzU4OWZDRDZlRGI2RTA4ZjRjN0MzMkQ0ZjcxYjU0YmRBMDI5MTMiLCJkZXNjcmlwdGlvbiI6IkZyZXNoIHJldmlzaW9uIG9mIFFtYXJrZXQgYXJ0aWZhY3QgYV94IiwibWF4QW1vdW50UmVxdWlyZWQiOiI1MDAwMDAwIiwibWF4VGltZW91dFNlY29uZHMiOjYwLCJtaW1lVHlwZSI6InRleHQvbWFya2Rvd24iLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXlUbyI6IjB4XHUwMDNjYWNjZXB0c1swXS5wYXlUb1x1MDAzZSIsInJlc291cmNlIjoiaHR0cHM6Ly9xbWFya2V0LmV4YW1wbGUvdjEvYXJ0aWZhY3RzL2FfeC9mcmVzaCIsInNjaGVtZSI6ImV4YWN0In0sInBheWxvYWQiOnsiYXV0aG9yaXphdGlvbiI6eyJmcm9tIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwibm9uY2UiOiIweFx1MDAzYzMyIHJhbmRvbSBieXRlcywgaGV4XHUwMDNlIiwidG8iOiIweFx1MDAzY2FjY2VwdHNbMF0ucGF5VG9cdTAwM2UiLCJ2YWxpZEFmdGVyIjoiMCIsInZhbGlkQmVmb3JlIjoiMTc2NzIyNTYwMCIsInZhbHVlIjoiNTAwMDAwMCJ9LCJzaWduYXR1cmUiOiIweFx1MDAzYzY1LWJ5dGUgRUlQLTcxMiBzaWduYXR1cmUsIGhleFx1MDAzZSJ9LCJ4NDAyVmVyc2lvbiI6Mn0=", "in": "header", "name": "PAYMENT-SIGNATURE", "required": false, "schema": { "format": "byte", "type": "string" } }, "signInWithX": { "description": "A CAIP-122 proof that you control a wallet, base64-encoded. Bound to this service's origin and spent once. No payment and no balance are involved -- it proves control, nothing else.", "in": "header", "name": "SIGN-IN-WITH-X", "required": true, "schema": { "format": "byte", "type": "string" } }, "xPayment": { "description": "x402 v1 payment, base64-encoded PaymentPayload. Present: settle on the wallet rail. Absent: quote a 402 (or, with a bearer key on an operation that takes credits, spend credits).", "example": "eyJhY2NlcHRlZCI6eyJhbW91bnQiOiI1MDAwMDAwIiwiYXNzZXQiOiIweDgzMzU4OWZDRDZlRGI2RTA4ZjRjN0MzMkQ0ZjcxYjU0YmRBMDI5MTMiLCJkZXNjcmlwdGlvbiI6IkZyZXNoIHJldmlzaW9uIG9mIFFtYXJrZXQgYXJ0aWZhY3QgYV94IiwibWF4QW1vdW50UmVxdWlyZWQiOiI1MDAwMDAwIiwibWF4VGltZW91dFNlY29uZHMiOjYwLCJtaW1lVHlwZSI6InRleHQvbWFya2Rvd24iLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXlUbyI6IjB4XHUwMDNjYWNjZXB0c1swXS5wYXlUb1x1MDAzZSIsInJlc291cmNlIjoiaHR0cHM6Ly9xbWFya2V0LmV4YW1wbGUvdjEvYXJ0aWZhY3RzL2FfeC9mcmVzaCIsInNjaGVtZSI6ImV4YWN0In0sInBheWxvYWQiOnsiYXV0aG9yaXphdGlvbiI6eyJmcm9tIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwibm9uY2UiOiIweFx1MDAzYzMyIHJhbmRvbSBieXRlcywgaGV4XHUwMDNlIiwidG8iOiIweFx1MDAzY2FjY2VwdHNbMF0ucGF5VG9cdTAwM2UiLCJ2YWxpZEFmdGVyIjoiMCIsInZhbGlkQmVmb3JlIjoiMTc2NzIyNTYwMCIsInZhbHVlIjoiNTAwMDAwMCJ9LCJzaWduYXR1cmUiOiIweFx1MDAzYzY1LWJ5dGUgRUlQLTcxMiBzaWduYXR1cmUsIGhleFx1MDAzZSJ9LCJ4NDAyVmVyc2lvbiI6Mn0=", "in": "header", "name": "X-PAYMENT", "required": false, "schema": { "format": "byte", "type": "string" } } }, "responses": { "AuthUnavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The token verifier could not be reached; whether the credential is good is unknown. Retry. Codes: `auth_unavailable`." }, "BadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request was understood and refused. Codes: `bad_body`, `bad_amount`, `bad_budget`, `bad_question`, `bad_request`, `bad_wallet`, `budget_met`, `not_fundable`." }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The request is well formed but the state moved. Codes: `price_changed`, `intent_closed`, `payment_state`, `payment_reused`." }, "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The account may not do this. Codes: `headstart`, `forbidden`." }, "Gone": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The top-up intent aged out unpaid; create a new one. Nothing was charged. Codes: `intent_expired`." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such row. Codes: `not_found`, `no_free_revision`." }, "PaymentRequired": { "content": { "application/json": { "example": { "x402Version": 2, "error": "payment required", "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "5000000", "maxAmountRequired": "5000000", "resource": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json", "payTo": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ], "resource": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json" }, "extensions": { "bazaar": { "info": { "input": { "body": {}, "bodyType": "json", "method": "POST", "type": "http" }, "output": { "type": "json" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "input": { "properties": { "body": { "type": "object" }, "bodyType": { "enum": [ "json" ] }, "method": { "enum": [ "GET", "POST" ] }, "type": { "const": "http" } }, "required": [ "type", "method" ], "type": "object" }, "output": { "properties": { "type": { "enum": [ "json", "text" ] } }, "required": [ "type" ], "type": "object" } }, "required": [ "input" ], "type": "object" } } }, "chainId": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } }, "schema": { "$ref": "#/components/schemas/PaymentRequired" } } }, "description": "Payment required. On a first request this is the quote; after a submitted payment it names why the payment was refused. Nothing was charged. Sign accepts[0] and retry with X-PAYMENT.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PAYMENT-REQUIRED" } } }, "RateLimited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many anonymous account creations from this address; Retry-After says when the window resets. Codes: `rate_limited`.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "SettlementUnresolved": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The facilitator was asked to settle and the outcome is unknown or unidentifiable. The money may have moved; the payment is on file for reconciliation. Do not pay again. Codes: `settle_unknown`, `settle_no_reference`." }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No usable credential. auth_required: none was sent where one is needed; invalid_key / invalid_token: one was sent and did not resolve -- fix it rather than retry. Codes: `auth_required`, `invalid_key`, `invalid_token`.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" } } }, "X402NotConfigured": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "This deployment cannot settle x402; pay with credits. Codes: `x402_not_configured`." } }, "schemas": { "AgentAccount": { "properties": { "account_id": { "type": "string" }, "api_key": { "description": "Shown once. Send as Authorization: Bearer.", "type": "string" }, "balance_credits": { "description": "Always 0 on creation: fund the account over x402 or Stripe.", "format": "int32", "type": "integer" }, "note": { "type": "string" } }, "required": [ "account_id", "api_key", "balance_credits", "note" ], "type": "object" }, "AgentAccountRequest": { "properties": { "label": { "description": "Free text, for the operator's own bookkeeping. Truncated to 60 characters.", "type": "string" }, "wallet_address": { "description": "Optional EVM address the agent will pay from.", "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" } }, "type": "object" }, "ArtifactSummary": { "properties": { "age_hours": { "description": "Age of the latest revision; null when none is published.", "format": "double", "nullable": true, "type": "number" }, "downloads": { "format": "int64", "type": "integer" }, "external_url": { "nullable": true, "type": "string" }, "freshness_hours": { "format": "int32", "type": "integer" }, "id": { "type": "string" }, "latest_rev": { "format": "int32", "type": "integer" }, "machine_price_cents": { "description": "The price of a fresh read after the first; the first read of an artifact is the trial price.", "format": "int32", "type": "integer" }, "question_id": { "type": "string" }, "teaser": { "additionalProperties": true, "description": "arbitrary JSON object", "nullable": true, "type": "object" }, "unique_buyers": { "format": "int64", "type": "integer" } }, "required": [ "age_hours", "downloads", "external_url", "freshness_hours", "id", "latest_rev", "machine_price_cents", "question_id", "teaser", "unique_buyers" ], "type": "object" }, "ArtifactsPage": { "properties": { "artifacts": { "items": { "$ref": "#/components/schemas/ArtifactSummary" }, "nullable": false, "type": "array" }, "next_cursor": { "description": "Send back as ?after= for the next page. Absent on the last page, and on a free-text search, which returns its best page and no cursor.", "type": "string" } }, "required": [ "artifacts" ], "type": "object" }, "ChainInfo": { "additionalProperties": false, "description": "The on-chain rail's configuration.", "properties": { "chain_reads_configured": { "description": "Whether a read-only node is configured. Configuration, not reachability: nothing is probed, so a node that is set and unreachable still reports true. False is definitive and means smart-contract wallet sign-in and settlement reconciliation are both inert -- a wallet that can pay may be unable to sign back in, and a settlement whose outcome was never learned stays unresolved.", "type": "boolean" }, "escrow": { "additionalProperties": false, "description": "The deployed per-question escrow descriptor, or null. Only these fields are published; all of them are readable on the chain.", "nullable": true, "properties": { "chain_id": { "type": "integer" }, "deployed_block": { "description": "An indexer's fromBlock.", "type": "integer" }, "factory": { "description": "The escrow factory address to call.", "type": "string" }, "implementation": { "type": "string" }, "network": { "type": "string" }, "platform": { "type": "string" }, "usdc": { "type": "string" } }, "type": "object" }, "network": { "type": "string" }, "pay_to": { "description": "Null when this deployment cannot settle x402.", "nullable": true, "type": "string" }, "usdc": { "description": "USDC contract address on the network.", "type": "string" } }, "required": [ "network", "usdc", "pay_to", "escrow", "chain_reads_configured" ], "type": "object" }, "Checkout": { "properties": { "checkout_url": { "type": "string" }, "session_id": { "type": "string" } }, "required": [ "checkout_url", "session_id" ], "type": "object" }, "CheckoutRequest": { "description": "Pass pack or amount_cents.", "properties": { "amount_cents": { "description": "Alternative to pack.", "format": "int64", "type": "integer" }, "pack": { "description": "A credit pack, in dollars.", "enum": [ "100", "20", "5", "" ], "type": "string" }, "purpose": { "enum": [ "", "credits", "fund" ], "type": "string" }, "question_id": { "type": "string" }, "return_path": { "type": "string" } }, "type": "object" }, "ClaimedRun": { "properties": { "proposal_id": { "nullable": true, "type": "string" }, "question_id": { "type": "string" }, "run_id": { "type": "string" }, "status": { "enum": [ "running" ], "type": "string" } }, "required": [ "proposal_id", "question_id", "run_id", "status" ], "type": "object" }, "CreditsLedger": { "properties": { "balance_credits": { "format": "int64", "type": "integer" }, "entries": { "items": { "$ref": "#/components/schemas/CreditsLedgerEntry" }, "nullable": false, "type": "array" } }, "required": [ "balance_credits", "entries" ], "type": "object" }, "CreditsLedgerEntry": { "properties": { "delta_credits": { "description": "Signed movement; a top-up is positive, a read or a fund is negative.", "format": "int32", "type": "integer" }, "reason": { "description": "Why the balance moved.", "example": "x402_topup", "type": "string" }, "ref": { "description": "The idempotency key for the reason: an x402 transaction, a Stripe session, a download id.", "nullable": true, "type": "string" }, "ts": { "format": "date-time", "type": "string" } }, "required": [ "delta_credits", "reason", "ref", "ts" ], "type": "object" }, "DiscoveryListing": { "description": "The x402 discovery listing shape (specification v2 §8), describing this deployment's paid resources.", "properties": { "items": { "items": { "properties": { "accepts": { "items": { "$ref": "#/components/schemas/PaymentRequirements" }, "type": "array" }, "lastUpdated": { "format": "date-time", "type": "string" }, "metadata": { "properties": { "amount": { "description": "\"fixed\" when accepts[0].maxAmountRequired is the price; \"per-request\" when the 402 quotes it (a read's price, the amount the caller asked to fund or buy).", "type": "string" }, "auth": { "enum": [ "none", "bearer" ], "type": "string" }, "description": { "type": "string" }, "input": { "description": "The bazaar extension's info.input for this resource.", "type": "object" }, "method": { "type": "string" }, "openapi": { "description": "The operation in /openapi.json.", "format": "uri", "type": "string" }, "output": { "type": "object" } }, "type": "object" }, "resource": { "description": "Absolute URL, with {param} placeholders for a templated route.", "type": "string" }, "type": { "enum": [ "http" ], "type": "string" }, "x402Version": { "type": "integer" } }, "required": [ "resource", "type", "x402Version", "accepts", "lastUpdated", "metadata" ], "type": "object" }, "type": "array" }, "pagination": { "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "limit", "offset", "total" ], "type": "object" }, "x402Version": { "enum": [ 2 ], "type": "integer" } }, "required": [ "x402Version", "items", "pagination" ], "type": "object" }, "EIP712Field": { "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "EIP712TypedData": { "description": "The EIP-712 document to sign for challenge.accepts[0], ready for eth_signTypedData_v4. The `exact` scheme on an EVM network is an EIP-3009 TransferWithAuthorization; everything but from, validAfter, validBefore and nonce is fixed by the challenge and filled in here.", "properties": { "domain": { "additionalProperties": { "description": "any JSON value" }, "description": "USDC's EIP-712 domain: name and version from accepts[0].extra, chainId, verifyingContract = accepts[0].asset.", "nullable": true, "type": "object" }, "fill": { "description": "What to replace and how to send the signature.", "type": "string" }, "message": { "additionalProperties": { "description": "any JSON value" }, "description": "to and value are final; from, validAfter, validBefore and nonce are placeholders in angle brackets.", "nullable": true, "type": "object" }, "primaryType": { "type": "string" }, "types": { "additionalProperties": { "items": { "$ref": "#/components/schemas/EIP712Field" }, "nullable": true, "type": "array" }, "nullable": true, "type": "object" } }, "required": [ "domain", "fill", "message", "primaryType", "types" ], "type": "object" }, "Error": { "description": "The body of every non-2xx response except a 402. Match on error.code; the message is for humans.", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "error" ], "type": "object" }, "ErrorBody": { "properties": { "code": { "description": "Stable machine-readable code. Shared with GraphQL extensions.code and MCP tool errors.", "example": "auth_required", "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "FailRunRequest": { "properties": { "reason": { "type": "string" } }, "type": "object" }, "FundRequest": { "properties": { "amount_cents": { "description": "How much to escrow. Clamped to what the round still needs.", "format": "int32", "maximum": 1000000, "minimum": 1, "type": "integer" } }, "required": [ "amount_cents" ], "type": "object" }, "FundResult": { "description": "What the contribution bought, and where to watch it.", "properties": { "budget_cents": { "format": "int32", "type": "integer" }, "escrowed_cents": { "description": "What this call actually escrowed, after clamping to the remainder.", "format": "int32", "type": "integer" }, "funding_position": { "type": "string" }, "question_id": { "type": "string" }, "question_status": { "enum": [ "curating", "listed", "rejected", "duplicate", "funded", "answering", "answered", "retired", "superseded" ], "type": "string" }, "run_id": { "description": "The research run this contribution scheduled. Present only on the contribution that completed the round -- that is the one that schedules it.", "type": "string" }, "status_url": { "description": "Poll this while question_status moves funded -\u003e answering -\u003e answered.", "format": "uri", "type": "string" }, "total_cents": { "format": "int64", "type": "integer" } }, "required": [ "budget_cents", "escrowed_cents", "funding_position", "question_id", "question_status", "status_url", "total_cents" ], "type": "object" }, "Health": { "description": "Readiness: ok is true while the database is reachable.", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "ListQuestionRequest": { "properties": { "budget_cents": { "description": "Research spend cap. Omit, null or 0 for no preference; otherwise 100–100000. 2000 and above runs the deep tier.", "nullable": true, "oneOf": [ { "enum": [ 0 ], "type": "integer" }, { "maximum": 100000, "minimum": 100, "type": "integer" } ], "type": "integer" }, "entities": { "items": { "maxLength": 14, "type": "string" }, "maxItems": 4, "nullable": true, "type": "array" }, "text": { "maxLength": 2000, "minLength": 12, "type": "string" }, "trigger": { "additionalProperties": { "description": "any JSON value" }, "description": "Optional watch trigger, passed through as JSON.", "nullable": true, "type": "object" } }, "required": [ "text" ], "type": "object" }, "ListQuestionResult": { "properties": { "budget_cents": { "format": "int32", "nullable": true, "type": "integer" }, "id": { "type": "string" }, "status": { "enum": [ "listed", "rejected", "duplicate", "curating" ], "type": "string" }, "tier": { "nullable": true, "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "Ok": { "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "PaymentAuthorization": { "description": "payload.authorization is the EIP-3009 message and payload.signature its EIP-712 signature; a top-up intent hands both out ready to fill in, as payment.x402.eip712.", "properties": { "authorization": { "properties": { "from": { "description": "The payer.", "type": "string" }, "nonce": { "description": "32 random bytes, hex. Never reuse one.", "type": "string" }, "to": { "description": "accepts[0].payTo.", "type": "string" }, "validAfter": { "type": "string" }, "validBefore": { "description": "Unix seconds; within accepts[0].maxTimeoutSeconds of now. Also what a settlement of unknown outcome is reconciled against, so it must be real.", "type": "string" }, "value": { "description": "accepts[0].amount.", "type": "string" } }, "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ], "type": "object" }, "signature": { "description": "EIP-712 signature of the authorization under the asset's domain (accepts[0].extra).", "type": "string" } }, "required": [ "signature", "authorization" ], "type": "object" }, "PaymentIntentStatus": { "description": "Where a top-up intent is. Poll until it is terminal.", "enum": [ "pending", "settled", "credited", "expired", "failed", "unresolved", "duplicate" ], "type": "string" }, "PaymentPayload": { "description": "The decoded PAYMENT-SIGNATURE (or X-PAYMENT) header: `exact` on an EVM network, in either wire version. Send it base64-encoded; bare JSON is also accepted.", "example": { "accepted": { "amount": "5000000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Fresh revision of Qmarket artifact a_x", "maxAmountRequired": "5000000", "maxTimeoutSeconds": 60, "mimeType": "text/markdown", "network": "eip155:8453", "payTo": "0x\u003caccepts[0].payTo\u003e", "resource": "https://qmarket.example/v1/artifacts/a_x/fresh", "scheme": "exact" }, "payload": { "authorization": { "from": "0x1111111111111111111111111111111111111111", "nonce": "0x\u003c32 random bytes, hex\u003e", "to": "0x\u003caccepts[0].payTo\u003e", "validAfter": "0", "validBefore": "1767225600", "value": "5000000" }, "signature": "0x\u003c65-byte EIP-712 signature, hex\u003e" }, "x402Version": 2 }, "oneOf": [ { "description": "x402Version 2. `accepted` is the accepts entry you signed, with its CAIP-2 network and `amount`.", "properties": { "accepted": { "$ref": "#/components/schemas/PaymentRequirements" }, "payload": { "$ref": "#/components/schemas/PaymentAuthorization" }, "x402Version": { "enum": [ 2 ], "type": "integer" } }, "required": [ "x402Version", "payload", "accepted" ], "title": "v2", "type": "object" }, { "description": "x402Version 1, still accepted. `network` is the bare name, not CAIP-2.", "properties": { "network": { "description": "Bare network name, e.g. base-sepolia.", "type": "string" }, "payload": { "$ref": "#/components/schemas/PaymentAuthorization" }, "scheme": { "enum": [ "exact" ], "type": "string" }, "x402Version": { "enum": [ 1 ], "type": "integer" } }, "required": [ "x402Version", "scheme", "network", "payload" ], "title": "v1", "type": "object" } ] }, "PaymentRequired": { "description": "The body of a 402, also served base64-encoded in the PAYMENT-REQUIRED response header. Sign accepts[0] and retry the same request with the payment in PAYMENT-SIGNATURE (or X-PAYMENT, which is still accepted).", "properties": { "accepts": { "items": { "$ref": "#/components/schemas/PaymentRequirements" }, "minItems": 1, "nullable": false, "type": "array" }, "chainId": { "description": "The EIP-155 chain id accepts[0].network stands for, for a client composing its own signature. Not part of the x402 wire shape; x402 clients ignore it.", "format": "int64", "type": "integer" }, "eip712": { "allOf": [ { "$ref": "#/components/schemas/EIP712TypedData" } ], "description": "The EIP-712 document to sign for accepts[0], ready for eth_signTypedData_v4 with from, validAfter, validBefore and nonce left as placeholders; `fill` says what replaces them and how the signature travels. Body only: the PAYMENT-REQUIRED header carries the challenge without it. Not part of the x402 wire shape; x402 clients ignore it.", "nullable": true, "type": "object" }, "error": { "description": "\"payment required\" on a first refusal; otherwise why a submitted payment was not accepted (bad_payment_header, verify_failed, settle_failed, facilitator_unreachable). Nothing was charged in either case.", "type": "string" }, "extensions": { "additionalProperties": { "description": "any JSON value" }, "description": "x402 v2 extensions carried on the v1 body. `bazaar` describes the request this resource takes, in the discovery extension's info shape.", "nullable": true, "type": "object" }, "resource": { "nullable": true, "properties": { "description": { "type": "string" }, "mimeType": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "x402Version": { "enum": [ 2 ], "format": "int64", "type": "integer" } }, "required": [ "accepts", "error", "x402Version" ], "type": "object" }, "PaymentRequirements": { "description": "One entry of a 402 challenge's accepts list: what to pay, where, on which network. x402 v2 `exact` scheme.", "properties": { "amount": { "description": "USDC atomic units (6 decimals) as a decimal string: cents × 10,000. The v2 name for the price.", "example": "5000000", "type": "string" }, "asset": { "description": "USDC contract address on `network`.", "type": "string" }, "description": { "type": "string" }, "extra": { "additionalProperties": { "type": "string" }, "description": "EIP-712 domain of the asset: {name, version}. Sign the TransferWithAuthorization against it.", "nullable": true, "type": "object" }, "maxAmountRequired": { "description": "The v1 name for amount, carrying the same value, sent for clients written against v1.", "example": "5000000", "type": "string" }, "maxTimeoutSeconds": { "description": "How long the signed authorization must remain valid.", "format": "int64", "type": "integer" }, "mimeType": { "description": "What a successful response is.", "type": "string" }, "network": { "description": "CAIP-2 chain identifier, e.g. eip155:8453 for Base mainnet or eip155:84532 for Base Sepolia.", "example": "eip155:8453", "type": "string" }, "payTo": { "description": "The address that receives the USDC. The zero address means this deployment cannot settle.", "type": "string" }, "resource": { "description": "Absolute URL of the resource being paid for.", "format": "uri", "type": "string" }, "scheme": { "enum": [ "exact" ], "type": "string" } }, "required": [ "amount", "asset", "description", "maxAmountRequired", "maxTimeoutSeconds", "mimeType", "network", "payTo", "resource", "scheme" ], "type": "object" }, "PublishRequest": { "properties": { "citations": { "format": "int32", "type": "integer" }, "content": { "description": "The report, markdown.", "minLength": 1, "type": "string" }, "cost_actual_cents": { "description": "What the run cost; prices the artifact as a markup on it.", "format": "int32", "nullable": true, "type": "integer" }, "teaser": { "description": "any JSON value" } }, "required": [ "content" ], "type": "object" }, "PublishResult": { "properties": { "artifact_id": { "type": "string" }, "rev": { "format": "int32", "type": "integer" } }, "required": [ "artifact_id", "rev" ], "type": "object" }, "Question": { "properties": { "artifact": { "allOf": [ { "$ref": "#/components/schemas/ArtifactSummary" } ], "nullable": true, "type": "object" }, "budget_cents": { "description": "The research budget the live proposal is measured against; null before curation attaches one.", "format": "int32", "nullable": true, "type": "integer" }, "created": { "type": "string" }, "entities": { "items": { "type": "string" }, "nullable": false, "type": "array" }, "forecasters": { "format": "int32", "nullable": true, "type": "integer" }, "funders": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "raised_cents": { "description": "Escrowed so far across every rail.", "format": "int64", "type": "integer" }, "ref_url": { "nullable": true, "type": "string" }, "slug": { "description": "The readable half of the question's URL: /q/{slug}-{id}. Decorative -- the id is what resolves -- so a link built from a stale slug still works.", "type": "string" }, "status": { "enum": [ "curating", "listed", "rejected", "duplicate", "funded", "answering", "answered", "retired", "superseded" ], "type": "string" }, "text": { "type": "string" }, "tier": { "nullable": true, "type": "string" } }, "required": [ "budget_cents", "created", "entities", "forecasters", "funders", "id", "raised_cents", "ref_url", "slug", "status", "text", "tier" ], "type": "object" }, "QuestionsPage": { "properties": { "next_cursor": { "description": "Send back as ?after= for the next page. Absent on the last page, and on a free-text search, which returns its best page and no cursor.", "type": "string" }, "questions": { "items": { "$ref": "#/components/schemas/Question" }, "nullable": false, "type": "array" } }, "required": [ "questions" ], "type": "object" }, "ReviewRequest": { "properties": { "canonical_text": { "type": "string" }, "notes": { "type": "string" }, "verdict": { "enum": [ "accept", "reject", "rewrite" ], "type": "string" } }, "required": [ "verdict" ], "type": "object" }, "ReviewResult": { "properties": { "bounty_cents": { "format": "int32", "type": "integer" }, "ok": { "type": "boolean" } }, "required": [ "bounty_cents", "ok" ], "type": "object" }, "RoyaltiesLedger": { "properties": { "accrued_cents": { "format": "int64", "type": "integer" }, "entries": { "items": { "$ref": "#/components/schemas/RoyaltyLedgerEntry" }, "nullable": false, "type": "array" } }, "required": [ "accrued_cents", "entries" ], "type": "object" }, "RoyaltyLedgerEntry": { "properties": { "artifact_id": { "type": "string" }, "cents": { "format": "int64", "type": "integer" }, "contributor_account": { "type": "string" }, "n": { "description": "How many downloads the row aggregates.", "format": "int64", "type": "integer" }, "role": { "type": "string" }, "status": { "enum": [ "accrued", "approved", "paid" ], "type": "string" } }, "required": [ "artifact_id", "cents", "contributor_account", "n", "role", "status" ], "type": "object" }, "SetLabelRequest": { "description": "A display name to claim.", "properties": { "label": { "type": "string" } }, "required": [ "label" ], "type": "object" }, "Settlement": { "description": "A settled payment, as the decoded X-Payment-Response header. error and detail are never set on a success.", "properties": { "detail": { "type": "string" }, "error": { "description": "Set only on a refused or unresolved settlement, never in the response header.", "type": "string" }, "network": { "type": "string" }, "payer": { "description": "The wallet that paid.", "type": "string" }, "tx": { "description": "On-chain transaction reference. It is the idempotency key: the same reference credits once.", "type": "string" } }, "type": "object" }, "TopUpIntent": { "description": "A credits top-up intent: the amount, the URL a wallet pays without a bearer key, the exact 402 it will answer with, and how to confirm the credits landed. Identical over REST, GraphQL and MCP.", "properties": { "account_id": { "type": "string" }, "amount_cents": { "description": "Credits the payment buys.", "format": "int32", "maximum": 1000000, "minimum": 100, "type": "integer" }, "balance_credits": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "credited_cents": { "format": "int32", "type": "integer" }, "detail": { "nullable": true, "type": "string" }, "expires_at": { "description": "created_at + 60 minutes. A pay attempt after this is refused with 410 intent_expired before the facilitator is called.", "format": "date-time", "type": "string" }, "intent_id": { "type": "string" }, "payer": { "nullable": true, "type": "string" }, "payment": { "$ref": "#/components/schemas/TopUpPayment" }, "status": { "$ref": "#/components/schemas/PaymentIntentStatus" }, "tx": { "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "verify": { "$ref": "#/components/schemas/TopUpVerify" } }, "required": [ "account_id", "amount_cents", "balance_credits", "created_at", "credited_cents", "detail", "expires_at", "intent_id", "payer", "payment", "status", "tx", "updated_at", "verify" ], "type": "object" }, "TopUpPayment": { "properties": { "auth": { "description": "No Authorization header: the intent id in the URL is the capability.", "enum": [ "none" ], "type": "string" }, "body": { "description": "Nothing is required; the amount is fixed by the intent. Always null.", "nullable": true, "type": "object" }, "content_type": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "x402": { "$ref": "#/components/schemas/TopUpX402" } }, "required": [ "auth", "body", "content_type", "method", "url", "x402" ], "type": "object" }, "TopUpRequest": { "properties": { "amount_cents": { "description": "Credits to buy: one cent is one credit.", "format": "int32", "maximum": 1000000, "minimum": 100, "type": "integer" } }, "required": [ "amount_cents" ], "type": "object" }, "TopUpResult": { "description": "A credited top-up. For a signup, account_id names the account the settlement opened and api_key is returned once.", "properties": { "account_id": { "type": "string" }, "api_key": { "type": "string" }, "balance_credits": { "format": "int64", "type": "integer" }, "credited_cents": { "format": "int32", "type": "integer" }, "intent_id": { "type": "string" }, "replay": { "type": "boolean" }, "tx": { "type": "string" } }, "required": [ "balance_credits", "credited_cents", "replay", "tx" ], "type": "object" }, "TopUpVerify": { "properties": { "auth": { "enum": [ "bearer" ], "type": "string" }, "credited_status": { "enum": [ "credited" ], "type": "string" }, "method": { "type": "string" }, "poll_seconds": { "format": "int64", "type": "integer" }, "terminal_statuses": { "items": { "type": "string" }, "nullable": false, "type": "array" }, "url": { "type": "string" } }, "required": [ "auth", "credited_status", "method", "poll_seconds", "terminal_statuses", "url" ], "type": "object" }, "TopUpX402": { "properties": { "chain_id": { "description": "EIP-155 chain id behind challenge.accepts[0].network (base: 8453, base-sepolia: 84532).", "format": "int64", "type": "integer" }, "challenge": { "$ref": "#/components/schemas/PaymentRequired" }, "eip712": { "$ref": "#/components/schemas/EIP712TypedData" }, "encoding": { "type": "string" }, "request_header": { "description": "Send the signed payment here. X-PAYMENT is also read, for clients written against v1.", "enum": [ "PAYMENT-SIGNATURE" ], "type": "string" }, "response_header": { "description": "The settlement comes back here and, for v1 clients, on X-Payment-Response as well.", "enum": [ "PAYMENT-RESPONSE" ], "type": "string" }, "version": { "enum": [ 2 ], "format": "int64", "type": "integer" } }, "required": [ "chain_id", "challenge", "eip712", "encoding", "request_header", "response_header", "version" ], "type": "object" }, "WalletKey": { "description": "A key minted for the account a wallet owns.", "properties": { "account_id": { "type": "string" }, "api_key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "account_id", "api_key" ], "type": "object" }, "WalletLabel": { "description": "The public name an account is displayed under.", "properties": { "account_id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "account_id", "label" ], "type": "object" }, "WatchRequest": { "properties": { "key": { "type": "string" }, "kind": { "description": "Defaults to entity.", "type": "string" } }, "required": [ "key" ], "type": "object" }, "WebhookResult": { "properties": { "credited": { "format": "int64", "type": "integer" }, "funding": { "nullable": true, "properties": { "budget_cents": { "format": "int32", "type": "integer" }, "escrowed_cents": { "format": "int32", "type": "integer" }, "funding_position": { "type": "string" }, "question_status": { "type": "string" }, "run_id": { "type": "string" }, "total_cents": { "format": "int64", "type": "integer" } }, "required": [ "budget_cents", "escrowed_cents", "funding_position", "question_status", "total_cents" ], "type": "object" }, "funding_error": { "type": "string" }, "handled": { "type": "boolean" }, "reason": { "type": "string" }, "type": { "type": "string" } }, "required": [ "handled" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "`Authorization: Bearer \u003ctoken\u003e`. A qm_sk_ agent key (mint one with the mintAgentKey GraphQL mutation, or POST /v1/accounts/agent with no credentials) or a Privy access token for a logged-in human. An invalid token is treated as anonymous, not refused: the handlers that need an account answer 401 auth_required.", "scheme": "bearer", "type": "http" }, "x402Payment": { "description": "x402 v1 payment: base64-encoded PaymentPayload signed against the 402's accepts[0]. Sending it is what selects the wallet rail over credits.", "in": "header", "name": "X-PAYMENT", "type": "apiKey" } } }, "info": { "description": "QMARKET is an exchange for research questions: anyone lists one, funders pool its budget, an executor answers it, and the report is sold. This document is generated from the running code -- schemas from the structs the handlers encode, bounds from the constants they validate against -- and the deployment's contract tests replay requests against it.\n\n**Auth.** Browse, teasers, freed revisions, the 402 challenge and the top-up pay URL need no credential. Everything else takes `Authorization: Bearer` (see bearerAuth). A missing or unknown token is anonymous, and the operations that need an account answer `401 auth_required`.\n\n**Paying.** Credits pay for reads and funding on every surface. USDC comes in over x402 v1 (`exact` scheme, see x-x402): a paid operation without a payment answers `402` with a PaymentRequired body, and the same request retried with `X-PAYMENT` settles through the facilitator and answers `200` with `X-Payment-Response`. An agent that cannot run that negotiation itself -- an MCP or GraphQL session -- mints a top-up intent instead and hands its bearer-free pay URL to any x402 wallet. Cards go through Stripe checkout.\n\n**Settlement outcomes.** A refused payment (`402` again, `error` naming why) charged nothing: sign and retry. `502 settle_unknown` / `settle_no_reference` means the money may have moved and delivery could not be confirmed; the payment is on file for reconciliation and must not be paid again. `503 x402_not_configured` means this deployment does not run the rail at all.\n\nStandalone JSON Schemas (2020-12) for every component are listed under x-json-schemas.", "title": "QMARKET API", "version": "1.1.0" }, "openapi": "3.0.3", "paths": { "/": { "get": { "description": "Every route, the auth model and how to pay, as prose in one JSON document. Start here or at /openapi.json.", "operationId": "index", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The index." } }, "security": [ {} ], "summary": "Service index", "tags": [ "meta" ] } }, "/graphql": { "post": { "description": "The same reads and writes in one round trip, plus login (authPrivy), key minting (mintAgentKey), viewer, and the top-up intent (createTopupIntent / topupIntent). The schema is served by introspection.", "operationId": "graphql", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "GraphQL response envelope." } }, "security": [ { "bearerAuth": [] }, {} ], "summary": "GraphQL", "tags": [ "meta" ] } }, "/healthz": { "get": { "description": "200 while the database is reachable, 503 when it is not. Readiness rather than liveness: a database outage must not restart every replica.", "operationId": "health", "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/Health" } } }, "description": "Ready." }, "503": { "content": { "application/json": { "example": { "ok": false }, "schema": { "$ref": "#/components/schemas/Health" } } }, "description": "Database unreachable." } }, "security": [ {} ], "summary": "Readiness probe", "tags": [ "meta" ] } }, "/llms.txt": { "get": { "description": "The llmstxt.org discovery file, rendered from this deployment's config.", "operationId": "llmsTxt", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "The file." } }, "security": [ {} ], "summary": "llms.txt", "tags": [ "meta" ] } }, "/mcp": { "post": { "description": "The marketplace as agent tools. Read-only tools are anonymous; the rest take the bearer key on this request. qmarket_create_topup_intent and qmarket_topup_status return the TopUpIntent object served by this API.", "operationId": "mcp", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "JSON-RPC response." } }, "security": [ { "bearerAuth": [] }, {} ], "summary": "MCP (streamable HTTP)", "tags": [ "meta" ] } }, "/openapi.json": { "get": { "operationId": "openapi", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OpenAPI 3.0.3." } }, "security": [ {} ], "summary": "This document", "tags": [ "meta" ] } }, "/robots.txt": { "get": { "description": "Allows every crawler and names the sitemap. Served from here because the Sitemap line has to be absolute and only this process knows the app's origin.", "operationId": "robotsTxt", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "The file." } }, "security": [ {} ], "summary": "robots.txt", "tags": [ "meta" ] } }, "/schemas/{name}": { "get": { "description": "JSON Schema 2020-12 with every referenced component under $defs. The names are the keys of components.schemas here.", "operationId": "schema", "parameters": [ { "description": "Component name, e.g. PaymentRequirements, Settlement, TopUpIntent, CreditsLedgerEntry, PaymentIntentStatus.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/schema+json": { "schema": { "type": "object" } } }, "description": "The schema." }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ {} ], "summary": "One component as a standalone JSON Schema", "tags": [ "meta" ] } }, "/sitemap.xml": { "get": { "description": "Every public question as a URL on the app origin, newest first, capped at 50,000. The path shape is /q/{slug}-{id}.", "operationId": "sitemap", "responses": { "200": { "content": { "application/xml": { "schema": { "type": "string" } } }, "description": "A urlset." } }, "security": [ {} ], "summary": "Sitemap", "tags": [ "meta" ] } }, "/v1/accounts/agent": { "post": { "description": "How an agent with no human gets a key: one anonymous POST returns an agent account and its qm_sk_ key. The balance is 0 -- nothing is granted -- so fund it with a top-up intent (POST /v1/credits/topup/intent) or POST /v1/credits/topup before a paid read. Rate-limited to 20 per client address per 1h0m0s.", "operationId": "createAgentAccount", "requestBody": { "content": { "application/json": { "example": { "label": "my-research-agent", "wallet_address": "0x1111111111111111111111111111111111111111" }, "schema": { "$ref": "#/components/schemas/AgentAccountRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccount" } } }, "description": "The account and its key, shown once." }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ {} ], "summary": "Create an agent account (no auth)", "tags": [ "accounts" ] } }, "/v1/accounts/key": { "post": { "description": "The way back in. An account opened by a settlement is handed its key once, in the response to the payment that created it; if that response is lost, the money moved and the credential did not arrive. Sign a SIWX proof for this service's origin, send it in SIGN-IN-WITH-X, and the account that wallet owns is issued a new key. Costs nothing and needs no balance: proving control of a wallet is not a payment. Rotating -- any previous key stops working, and the account owner is notified. A wallet that owns no account is wallet_unknown: a signature is free to produce and must not be able to create an account. Each proof is spent once.", "operationId": "mintWalletKey", "parameters": [ { "$ref": "#/components/parameters/signInWithX" } ], "responses": { "200": { "content": { "application/json": { "example": { "account_id": "acct_1", "api_key": "qm_sk_...", "label": "agent-k4m2p" }, "schema": { "$ref": "#/components/schemas/WalletKey" } } }, "description": "A new key." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ {} ], "summary": "Mint a key with a wallet signature (no bearer key)", "tags": [ "payments" ] } }, "/v1/accounts/label": { "post": { "description": "An account opened by a payment is displayed under a generated pseudonym, because the funder list is public and a wallet address on it is not something a funder chose to publish. This replaces it with a name you pick, authorized by a SIWX proof from the wallet that owns the account. Names are 3-32 characters of lowercase letters, digits and hyphens, unique among chosen names, and cannot start with agent- (that prefix is the generated ones). A name somebody else holds is label_taken.", "operationId": "setWalletLabel", "parameters": [ { "$ref": "#/components/parameters/signInWithX" } ], "requestBody": { "content": { "application/json": { "example": { "label": "orbital-research" }, "schema": { "$ref": "#/components/schemas/SetLabelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "account_id": "acct_1", "label": "orbital-research" }, "schema": { "$ref": "#/components/schemas/WalletLabel" } } }, "description": "The new name." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ {} ], "summary": "Set your display name (wallet signature)", "tags": [ "payments" ] } }, "/v1/artifacts": { "get": { "operationId": "listArtifacts", "parameters": [ { "description": "Filter to one entity.", "in": "query", "name": "entity", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/after" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactsPage" } } }, "description": "A page." } }, "security": [ {} ], "summary": "Browse artifacts", "tags": [ "artifacts" ] } }, "/v1/artifacts/{aid}/fresh": { "get": { "description": "The access rule decides first: funders and buyers of this revision read free (X-Qmarket-Access: owned), a revision past the freshness window is free, and one inside the head-start window is funders-only (403 headstart -- wait, do not retry). Otherwise it is for sale: a bearer key spends credits, X-PAYMENT settles USDC anonymously, and neither answers 402.", "operationId": "fresh", "parameters": [ { "description": "Artifact id.", "in": "path", "name": "aid", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/paymentSignature" }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "content": { "text/markdown": { "schema": { "type": "string" } } }, "description": "The revision.", "headers": { "Cache-Control": { "schema": { "enum": [ "private, no-store" ], "type": "string" } }, "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" }, "X-Payment-Response": { "$ref": "#/components/headers/X-Payment-Response" }, "X-Qmarket-Access": { "$ref": "#/components/headers/X-Qmarket-Access" }, "X-Qmarket-Price-Cents": { "$ref": "#/components/headers/X-Qmarket-Price-Cents" } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/SettlementUnresolved" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ { "bearerAuth": [] }, { "x402Payment": [] }, {} ], "summary": "Current revision (paid)", "tags": [ "artifacts", "payments" ] } }, "/v1/artifacts/{aid}/stale": { "get": { "description": "A revision is free once a newer one supersedes it or it ages past the freshness window. 404 no_free_revision while none has.", "operationId": "stale", "parameters": [ { "description": "Artifact id.", "in": "path", "name": "aid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/markdown": { "schema": { "type": "string" } } }, "description": "The revision.", "headers": { "Cache-Control": { "schema": { "enum": [ "private, no-store" ], "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ {} ], "summary": "Newest freed revision (free)", "tags": [ "artifacts" ] } }, "/v1/artifacts/{aid}/teaser": { "get": { "operationId": "teaser", "parameters": [ { "description": "Artifact id.", "in": "path", "name": "aid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactSummary" } } }, "description": "The summary." }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ {} ], "summary": "Teaser (free)", "tags": [ "artifacts" ] } }, "/v1/chain": { "get": { "operationId": "chain", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainInfo" } } }, "description": "Network, USDC asset, pay-to and escrow descriptor." } }, "security": [ {} ], "summary": "On-chain rail configuration", "tags": [ "payments" ] } }, "/v1/credits/topup": { "post": { "description": "The one-request on-ramp: without X-PAYMENT it quotes a 402 for amount_cents; with one it settles and credits. The caller must hold the bearer key and drive the x402 retry itself. A client that cannot -- an MCP or GraphQL session, or a wallet that will not carry a bearer key -- should create a top-up intent instead.", "operationId": "topUp", "parameters": [ { "$ref": "#/components/parameters/paymentSignature" }, { "$ref": "#/components/parameters/xPayment" } ], "requestBody": { "content": { "application/json": { "example": { "amount_cents": 500 }, "schema": { "$ref": "#/components/schemas/TopUpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "credited_cents": 500, "balance_credits": 1250, "tx": "0xabc123", "replay": false }, "schema": { "$ref": "#/components/schemas/TopUpResult" } } }, "description": "Credited.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" }, "X-Payment-Response": { "$ref": "#/components/headers/X-Payment-Response" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "$ref": "#/components/responses/SettlementUnresolved" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "x402Payment": [] } ], "summary": "Buy credits with USDC (same-request x402)", "tags": [ "payments" ] } }, "/v1/credits/topup/intent": { "post": { "description": "Mints a pending intent for amount_cents and returns everything needed to pay it: a URL under /v1/pay/topup/ that takes no bearer key, the exact 402 that URL answers with (sign accepts[0] without provoking it), and the status URL to poll. The intent id is the capability: holding it lets a wallet put money on this account and nothing else. Expires after 1h0m0s.", "operationId": "createTopUpIntent", "requestBody": { "content": { "application/json": { "example": { "amount_cents": 500 }, "schema": { "$ref": "#/components/schemas/TopUpRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "intent_id": "xp_00000000example0", "status": "pending", "account_id": "acc_example", "amount_cents": 500, "credited_cents": 0, "balance_credits": 0, "tx": null, "payer": null, "detail": null, "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T01:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "payment": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "method": "POST", "auth": "none", "content_type": "application/json", "body": null, "x402": { "version": 2, "request_header": "PAYMENT-SIGNATURE", "response_header": "PAYMENT-RESPONSE", "encoding": "base64(json)", "challenge": { "x402Version": 2, "error": "payment required", "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "5000000", "maxAmountRequired": "5000000", "resource": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json", "payTo": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ], "resource": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json" }, "extensions": { "bazaar": { "info": { "input": { "body": {}, "bodyType": "json", "method": "POST", "type": "http" }, "output": { "type": "json" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "input": { "properties": { "body": { "type": "object" }, "bodyType": { "enum": [ "json" ] }, "method": { "enum": [ "GET", "POST" ] }, "type": { "const": "http" } }, "required": [ "type", "method" ], "type": "object" }, "output": { "properties": { "type": { "enum": [ "json", "text" ] } }, "required": [ "type" ], "type": "object" } }, "required": [ "input" ], "type": "object" } } }, "chainId": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } }, "chain_id": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } } }, "verify": { "url": "https://api.qmarket.eternis.ai/v1/credits/topup/intent/xp_00000000example0", "method": "GET", "auth": "bearer", "credited_status": "credited", "terminal_statuses": [ "credited", "expired", "failed", "unresolved", "duplicate" ], "poll_seconds": 5 } }, "schema": { "$ref": "#/components/schemas/TopUpIntent" } } }, "description": "The intent." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a top-up intent", "tags": [ "payments" ] } }, "/v1/credits/topup/intent/{id}": { "get": { "description": "The intent as its owner sees it. status is the field to watch; credited means the balance moved and balance_credits is the result. Another account's intent is 404.", "operationId": "getTopUpIntent", "parameters": [ { "description": "Intent id.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "intent_id": "xp_00000000example0", "status": "pending", "account_id": "acc_example", "amount_cents": 500, "credited_cents": 0, "balance_credits": 0, "tx": null, "payer": null, "detail": null, "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T01:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "payment": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "method": "POST", "auth": "none", "content_type": "application/json", "body": null, "x402": { "version": 2, "request_header": "PAYMENT-SIGNATURE", "response_header": "PAYMENT-RESPONSE", "encoding": "base64(json)", "challenge": { "x402Version": 2, "error": "payment required", "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "5000000", "maxAmountRequired": "5000000", "resource": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json", "payTo": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ], "resource": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json" }, "extensions": { "bazaar": { "info": { "input": { "body": {}, "bodyType": "json", "method": "POST", "type": "http" }, "output": { "type": "json" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "input": { "properties": { "body": { "type": "object" }, "bodyType": { "enum": [ "json" ] }, "method": { "enum": [ "GET", "POST" ] }, "type": { "const": "http" } }, "required": [ "type", "method" ], "type": "object" }, "output": { "properties": { "type": { "enum": [ "json", "text" ] } }, "required": [ "type" ], "type": "object" } }, "required": [ "input" ], "type": "object" } } }, "chainId": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } }, "chain_id": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } } }, "verify": { "url": "https://api.qmarket.eternis.ai/v1/credits/topup/intent/xp_00000000example0", "method": "GET", "auth": "bearer", "credited_status": "credited", "terminal_statuses": [ "credited", "expired", "failed", "unresolved", "duplicate" ], "poll_seconds": 5 } }, "schema": { "$ref": "#/components/schemas/TopUpIntent" } } }, "description": "The intent." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ], "summary": "Verify a top-up intent", "tags": [ "payments" ] } }, "/v1/curation/{qid}/review": { "post": { "operationId": "review", "parameters": [ { "description": "Question id.", "in": "path", "name": "qid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewResult" } } }, "description": "Applied." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ], "summary": "Human curation verdict", "tags": [ "curation" ] } }, "/v1/feed": { "get": { "operationId": "feed", "parameters": [ { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionsPage" } } }, "description": "Questions ranked by the account's watches." }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "Personalized feed", "tags": [ "questions" ] } }, "/v1/ledger/credits": { "get": { "operationId": "creditsLedger", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsLedger" } } }, "description": "The ledger, newest first, 100 entries." }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "Credit balance and recent entries", "tags": [ "payments" ] } }, "/v1/ledger/royalties": { "get": { "operationId": "royaltiesLedger", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoyaltiesLedger" } } }, "description": "Accruals by artifact and role." }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "Royalty accruals", "tags": [ "payments" ] } }, "/v1/pay/topup": { "post": { "description": "The way in for a wallet with no account. Takes no Authorization header, because the caller has none -- that is the situation this answers. Mints an unbound intent for amount_cents and returns the URL that pays it and the exact 402 that URL answers with. Nothing is created here: pay the intent and the settlement opens the account, binds it to the wallet that paid, credits it, and returns account_id with api_key once. An intent nobody pays expires after 1h0m0s having created no account and no key. A second payment from a wallet that already has an account is credited to it and returns no key, because the key was already issued.", "operationId": "createSignupIntent", "requestBody": { "content": { "application/json": { "example": { "amount_cents": 500 }, "schema": { "$ref": "#/components/schemas/TopUpRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "intent_id": "xp_00000000example0", "status": "pending", "account_id": "acc_example", "amount_cents": 500, "credited_cents": 0, "balance_credits": 0, "tx": null, "payer": null, "detail": null, "created_at": "2026-01-01T00:00:00Z", "expires_at": "2026-01-01T01:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "payment": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "method": "POST", "auth": "none", "content_type": "application/json", "body": null, "x402": { "version": 2, "request_header": "PAYMENT-SIGNATURE", "response_header": "PAYMENT-RESPONSE", "encoding": "base64(json)", "challenge": { "x402Version": 2, "error": "payment required", "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "5000000", "maxAmountRequired": "5000000", "resource": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json", "payTo": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ], "resource": { "url": "https://api.qmarket.eternis.ai/v1/pay/topup/xp_00000000example0", "description": "Qmarket credits for acc_example", "mimeType": "application/json" }, "extensions": { "bazaar": { "info": { "input": { "body": {}, "bodyType": "json", "method": "POST", "type": "http" }, "output": { "type": "json" } }, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "input": { "properties": { "body": { "type": "object" }, "bodyType": { "enum": [ "json" ] }, "method": { "enum": [ "GET", "POST" ] }, "type": { "const": "http" } }, "required": [ "type", "method" ], "type": "object" }, "output": { "properties": { "type": { "enum": [ "json", "text" ] } }, "required": [ "type" ], "type": "object" } }, "required": [ "input" ], "type": "object" } } }, "chainId": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } }, "chain_id": 8453, "eip712": { "domain": { "chainId": 8453, "name": "USD Coin", "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "version": "2" }, "primaryType": "TransferWithAuthorization", "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "TransferWithAuthorization": [ { "name": "from", "type": "address" }, { "name": "to", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "validAfter", "type": "uint256" }, { "name": "validBefore", "type": "uint256" }, { "name": "nonce", "type": "bytes32" } ] }, "message": { "from": "\u003cyour address\u003e", "nonce": "\u003c0x + 32 random bytes as hex; never reuse one\u003e", "to": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "validAfter": "\u003cunix seconds, a few minutes in the past\u003e", "validBefore": "\u003cunix seconds, at most 60 ahead of now\u003e", "value": "5000000" }, "fill": "Replace from, validAfter, validBefore and nonce; sign the result with eth_signTypedData_v4 (the domain is the USDC contract's, not this service's). Then send base64({\"x402Version\":2,\"payload\":{\"signature\":\u003csig\u003e,\"authorization\":\u003cmessage\u003e},\"accepted\":\u003cthe accepts entry you signed\u003e}) in the PAYMENT-SIGNATURE header. A v1 payload in X-PAYMENT is still accepted. value and the message fields are decimal strings." } } }, "verify": { "url": "https://api.qmarket.eternis.ai/v1/credits/topup/intent/xp_00000000example0", "method": "GET", "auth": "bearer", "credited_status": "credited", "terminal_statuses": [ "credited", "expired", "failed", "unresolved", "duplicate" ], "poll_seconds": 5 } }, "schema": { "$ref": "#/components/schemas/TopUpIntent" } } }, "description": "The intent." }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ {} ], "summary": "Open an account by paying (no bearer key)", "tags": [ "payments" ] } }, "/v1/pay/topup/{id}": { "post": { "description": "The wallet half of the intent. No body, no Authorization header. Without X-PAYMENT: the 402 for the intent's amount. With it: settle and credit the intent's account, answering 200 with X-Payment-Response. Idempotent -- the same payment retried answers the same result with replay: true, and a settlement whose credit did not land the first time is completed rather than charged again. A refused payment answers 402 again with error naming why; nothing was charged and the intent stays payable.", "operationId": "payTopUpIntent", "parameters": [ { "description": "Intent id.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/paymentSignature" }, { "$ref": "#/components/parameters/xPayment" } ], "responses": { "200": { "content": { "application/json": { "example": { "intent_id": "xp_00000000example0", "credited_cents": 500, "balance_credits": 1250, "tx": "0xabc123", "replay": false }, "schema": { "$ref": "#/components/schemas/TopUpResult" } } }, "description": "Credited.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PAYMENT-RESPONSE" }, "X-Payment-Response": { "$ref": "#/components/headers/X-Payment-Response" } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "502": { "$ref": "#/components/responses/SettlementUnresolved" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ { "x402Payment": [] }, {} ], "summary": "Pay a top-up intent (no bearer key)", "tags": [ "payments" ] } }, "/v1/questions": { "get": { "operationId": "listQuestions", "parameters": [ { "description": "Filter by status.", "in": "query", "name": "status", "schema": { "enum": [ "listed", "funded", "answered" ], "type": "string" } }, { "description": "Filter to one entity, e.g. MRNA.", "in": "query", "name": "entity", "schema": { "type": "string" } }, { "description": "Free-text search.", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Ranking.", "in": "query", "name": "sort", "schema": { "enum": [ "relevance", "raised", "budget", "forecasters", "newest" ], "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/after" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionsPage" } } }, "description": "A page." } }, "security": [ {} ], "summary": "Browse questions", "tags": [ "questions" ] }, "post": { "description": "Free. Curation runs inline, so the response says whether it was listed, rejected or a duplicate, and what the research will cost.", "operationId": "listQuestion", "requestBody": { "content": { "application/json": { "example": { "budget_cents": 2000, "entities": [ "MRNA" ], "text": "Will MRNA report positive phase 3 data for its flu vaccine by Q2 2027?" }, "schema": { "$ref": "#/components/schemas/ListQuestionRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQuestionResult" } } }, "description": "Curated." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "List a question", "tags": [ "questions" ] } }, "/v1/questions/{qid}": { "get": { "operationId": "getQuestion", "parameters": [ { "description": "Question id.", "in": "path", "name": "qid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } }, "description": "The question." }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ {} ], "summary": "One question", "tags": [ "questions" ] } }, "/v1/questions/{qid}/fund": { "post": { "description": "A bearer key spends credits. A bearer key plus X-PAYMENT settles USDC over x402 instead -- the header decides the rail. Funding always needs an account, because the funder reads free afterwards and an expiry refund is a credit grant. The round is validated before the facilitator is called, so a refused fund never charged.", "operationId": "fundQuestion", "parameters": [ { "description": "Question id.", "in": "path", "name": "qid", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/paymentSignature" }, { "$ref": "#/components/parameters/xPayment" } ], "requestBody": { "content": { "application/json": { "example": { "amount_cents": 500 }, "schema": { "$ref": "#/components/schemas/FundRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundResult" } } }, "description": "Escrowed." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "$ref": "#/components/responses/SettlementUnresolved" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "x402Payment": [] } ], "summary": "Fund a question", "tags": [ "questions", "payments" ] } }, "/v1/runs/claim": { "post": { "operationId": "claimRun", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimedRun" } } }, "description": "A run, now running." }, "204": { "description": "Nothing scheduled." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [] } ], "summary": "Claim the next scheduled run", "tags": [ "executor" ] } }, "/v1/runs/{rid}/fail": { "post": { "operationId": "failRun", "parameters": [ { "description": "Run id.", "in": "path", "name": "rid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailRunRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } }, "description": "Recorded." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ], "summary": "Record a failed run", "tags": [ "executor" ] } }, "/v1/runs/{rid}/publish": { "post": { "operationId": "publishRun", "parameters": [ { "description": "Run id.", "in": "path", "name": "rid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResult" } } }, "description": "The revision written (or the one already written for this run)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [] } ], "summary": "Publish a run's report", "tags": [ "executor" ] } }, "/v1/stripe/checkout": { "post": { "operationId": "stripeCheckout", "requestBody": { "content": { "application/json": { "example": { "pack": "20" }, "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } }, "description": "Redirect the payer to checkout_url." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/X402NotConfigured" } }, "security": [ { "bearerAuth": [] } ], "summary": "Start a Stripe Checkout for credits", "tags": [ "payments" ] } }, "/v1/stripe/webhook": { "post": { "description": "Called by Stripe, authenticated by Stripe-Signature. Crediting is idempotent on the session id.", "operationId": "stripeWebhook", "parameters": [ { "in": "header", "name": "Stripe-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResult" } } }, "description": "Applied." }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ {} ], "summary": "Stripe webhook", "tags": [ "payments" ] } }, "/v1/watches": { "post": { "operationId": "watch", "requestBody": { "content": { "application/json": { "example": { "key": "MRNA", "kind": "entity" }, "schema": { "$ref": "#/components/schemas/WatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } }, "description": "Watching." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "Watch an entity", "tags": [ "accounts" ] } }, "/x402/discovery/resources": { "get": { "description": "This deployment's x402-paid resources in the discovery listing shape of the x402 v2 specification (§8), self-hosted: the deployment speaks x402 v1 on the wire, so it is not cataloged by a facilitator's Bazaar. Empty when x402 is not configured.", "operationId": "discoveryResources", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryListing" } } }, "description": "The listing." } }, "security": [ {} ], "summary": "x402 discovery listing", "tags": [ "meta", "payments" ] } } }, "security": [ {} ], "servers": [ { "url": "https://api.qmarket.eternis.ai" } ], "tags": [ { "description": "Discovery: the index, health, llms.txt, this document, the schemas.", "name": "meta" }, { "name": "questions" }, { "name": "artifacts" }, { "description": "Credits, x402 top-ups, Stripe, ledgers.", "name": "payments" }, { "name": "accounts" }, { "description": "Internal accounts only: the run queue.", "name": "executor" }, { "description": "Internal accounts only.", "name": "curation" } ], "x-json-schemas": [ "https://api.qmarket.eternis.ai/schemas/AgentAccount", "https://api.qmarket.eternis.ai/schemas/AgentAccountRequest", "https://api.qmarket.eternis.ai/schemas/ArtifactSummary", "https://api.qmarket.eternis.ai/schemas/ArtifactsPage", "https://api.qmarket.eternis.ai/schemas/ChainInfo", "https://api.qmarket.eternis.ai/schemas/Checkout", "https://api.qmarket.eternis.ai/schemas/CheckoutRequest", "https://api.qmarket.eternis.ai/schemas/ClaimedRun", "https://api.qmarket.eternis.ai/schemas/CreditsLedger", "https://api.qmarket.eternis.ai/schemas/CreditsLedgerEntry", "https://api.qmarket.eternis.ai/schemas/DiscoveryListing", "https://api.qmarket.eternis.ai/schemas/EIP712Field", "https://api.qmarket.eternis.ai/schemas/EIP712TypedData", "https://api.qmarket.eternis.ai/schemas/Error", "https://api.qmarket.eternis.ai/schemas/ErrorBody", "https://api.qmarket.eternis.ai/schemas/FailRunRequest", "https://api.qmarket.eternis.ai/schemas/FundRequest", "https://api.qmarket.eternis.ai/schemas/FundResult", "https://api.qmarket.eternis.ai/schemas/Health", "https://api.qmarket.eternis.ai/schemas/ListQuestionRequest", "https://api.qmarket.eternis.ai/schemas/ListQuestionResult", "https://api.qmarket.eternis.ai/schemas/Ok", "https://api.qmarket.eternis.ai/schemas/PaymentAuthorization", "https://api.qmarket.eternis.ai/schemas/PaymentIntentStatus", "https://api.qmarket.eternis.ai/schemas/PaymentPayload", "https://api.qmarket.eternis.ai/schemas/PaymentRequired", "https://api.qmarket.eternis.ai/schemas/PaymentRequirements", "https://api.qmarket.eternis.ai/schemas/PublishRequest", "https://api.qmarket.eternis.ai/schemas/PublishResult", "https://api.qmarket.eternis.ai/schemas/Question", "https://api.qmarket.eternis.ai/schemas/QuestionsPage", "https://api.qmarket.eternis.ai/schemas/ReviewRequest", "https://api.qmarket.eternis.ai/schemas/ReviewResult", "https://api.qmarket.eternis.ai/schemas/RoyaltiesLedger", "https://api.qmarket.eternis.ai/schemas/RoyaltyLedgerEntry", "https://api.qmarket.eternis.ai/schemas/SetLabelRequest", "https://api.qmarket.eternis.ai/schemas/Settlement", "https://api.qmarket.eternis.ai/schemas/TopUpIntent", "https://api.qmarket.eternis.ai/schemas/TopUpPayment", "https://api.qmarket.eternis.ai/schemas/TopUpRequest", "https://api.qmarket.eternis.ai/schemas/TopUpResult", "https://api.qmarket.eternis.ai/schemas/TopUpVerify", "https://api.qmarket.eternis.ai/schemas/TopUpX402", "https://api.qmarket.eternis.ai/schemas/WalletKey", "https://api.qmarket.eternis.ai/schemas/WalletLabel", "https://api.qmarket.eternis.ai/schemas/WatchRequest", "https://api.qmarket.eternis.ai/schemas/WebhookResult" ], "x-x402": { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "bounds": { "budgetCents": { "max": 100000, "min": 100, "zeroMeansUnset": true }, "deepTierFrom": 2000, "fundCents": { "max": 1000000, "min": 1 }, "topUpCents": { "max": 1000000, "min": 100 } }, "chainId": 8453, "discovery": "https://api.qmarket.eternis.ai/x402/discovery/resources", "enabled": true, "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402", "network": "eip155:8453", "networkName": "base", "payTo": "0xd24961d32C459170A6784220858Cf41C5c4B0900", "requestHeader": "PAYMENT-SIGNATURE", "responseHeader": "PAYMENT-RESPONSE", "scheme": "exact", "signing": "EIP-3009 TransferWithAuthorization under USDC's EIP-712 domain. Every 402 body carries the typed data ready to sign as `eip712`, with `chainId` beside it; a top-up intent carries the same document as payment.x402.eip712.", "topUpIntent": { "create": "POST https://api.qmarket.eternis.ai/v1/credits/topup/intent", "pay": "POST https://api.qmarket.eternis.ai/v1/pay/topup/{intent_id}", "ttl": "1h0m0s", "verify": "GET https://api.qmarket.eternis.ai/v1/credits/topup/intent/{intent_id}" }, "v1": "Still accepted. A payment sent as a v1 PaymentPayload in X-PAYMENT settles, and the settlement comes back on X-Payment-Response as well as PAYMENT-RESPONSE. The challenge itself is v2 only: `network` holds a CAIP-2 identifier, which is the one field that cannot carry both versions at once. `maxAmountRequired` is sent beside `amount` for the same reason it can be.", "wireVersion": 2 } }