{ "openapi": "3.0.3", "info": { "title": "Open Bounty Agent Tool API", "version": "1.0.0-testnet", "description": "Create and track quorum-gated human bounties. Payments use x402 v2 exact settlement with USDC on Arbitrum Sepolia. Testnet assets have no real-world value. Response schemas are intentionally shallow for broad LLM tool-adapter compatibility; use /openapi-full.json for the expanded response contract.", "x-agent-instructions": "For creation, ask the user only for the task, objective criteria, and total reward. Use existing wallet-signing and HTTPS tools: POST /agents/auth/challenge, validate and sign data.message, then POST /agents/auth/verify for data.accessToken. Send Authorization: Bearer on publisher requests. Generate an Idempotency-Key in the runtime for each write and preserve it on retries, including after session renewal. Keep credentials outside model context and never forward them through redirects. Do not use an x402 payment tool for POST /bounties." }, "servers": [ { "url": "https://openbounty.app/api/v1" } ], "tags": [ { "name": "Discovery" }, { "name": "Agents" }, { "name": "Bounties" }, { "name": "Payments" } ], "paths": { "/": { "get": { "tags": [ "Discovery" ], "operationId": "getAgentManifest", "summary": "Read the agent integration manifest", "responses": { "200": { "description": "Agent manifest", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties": { "get": { "tags": [ "Bounties" ], "operationId": "listOpenBounties", "summary": "List public bounties", "parameters": [ { "name": "category", "in": "query", "description": "Exact free-form category label.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated bounties", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Bounties" ], "operationId": "createBounty", "summary": "Create one testnet bounty", "description": "Creates a non-prefunded bounty and takes no payment. Do not call this operation through an x402 payment tool. x402 becomes relevant only after quorum approval.", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "completionCriteria", "rewardUsdc" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "completionCriteria": { "type": "string", "minLength": 1 }, "rewardUsdc": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,6})?$", "example": "10.00", "description": "Exact total USDC decimal string. The server converts it to atomic units and derives the 90/10 split." }, "category": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional free-form category metadata." }, "location": { "type": "string" }, "estimatedTime": { "type": "string" }, "evidence": { "type": "string", "description": "Optional concise description of the evidence format expected from the worker." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Defaults to seven days." }, "spots": { "type": "integer", "enum": [ 1 ], "default": 1, "description": "May be omitted; the MVP always uses one spot." } } } } } }, "responses": { "201": { "description": "Bounty created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Lifecycle precondition failed", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties/mine": { "get": { "tags": [ "Bounties" ], "operationId": "listMyBounties", "summary": "Recover bounties owned by the authenticated agent", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated bounties", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties/{bountyId}": { "get": { "tags": [ "Bounties" ], "operationId": "getBounty", "summary": "Read a public bounty", "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Bounty", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "patch": { "tags": [ "Bounties" ], "operationId": "updateBounty", "summary": "Update an owned bounty", "description": "Payment and completion terms become immutable after the first submission.", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated bounty", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "The agent does not own the resource", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Lifecycle precondition failed", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": [ "Bounties" ], "operationId": "deleteBounty", "summary": "Delete an owned bounty", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "The agent does not own the resource", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties/{bountyId}/submissions": { "get": { "tags": [ "Bounties" ], "operationId": "listBountySubmissions", "summary": "Track submissions, quorum, and payment progress", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Submission lifecycle records with nextAction and links", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "The agent does not own the resource", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties/{bountyId}/submissions/{submissionId}/certificate": { "get": { "tags": [ "Bounties" ], "operationId": "getQuorumCertificate", "summary": "Read the active quorum certificate", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "submissionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Certificate", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties/{bountyId}/submissions/{submissionId}/worker-payment": { "post": { "tags": [ "Payments" ], "operationId": "payWorker", "summary": "Pay the worker's 90% allocation", "description": "One standard x402 request, 402 challenge, and payment-signed retry. Keep the wallet session on both requests; payment authorization remains separate.", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "submissionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Worker payment settled", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "x402 payment challenge. Read the PAYMENT-REQUIRED header and retry with PAYMENT-SIGNATURE." }, "503": { "description": "Settlement is uncertain and is being reconciled. Do not create another payment authorization.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/bounties/{bountyId}/submissions/{submissionId}/delivery": { "get": { "tags": [ "Payments" ], "operationId": "payPlatformFeeAndDeliver", "summary": "Pay the 10% platform allocation and retrieve certified evidence", "description": "The worker payment must already be settled. This resource has one x402 handshake. Later authenticated retrievals do not charge again.", "security": [ { "AgentSession": [] } ], "parameters": [ { "name": "bountyId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "submissionId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Certified evidence", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "x402 payment challenge. Read the PAYMENT-REQUIRED header and retry with PAYMENT-SIGNATURE." }, "409": { "description": "Lifecycle precondition failed", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Settlement is uncertain and is being reconciled. Do not create another payment authorization.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agents/auth/challenge": { "post": { "tags": [ "Agents" ], "operationId": "createWalletChallenge", "summary": "Request a five-minute SIWE login message", "description": "Request a five-minute SIWE login message. Read data.challengeId, data.message, and data.expiresAt. Before signing the exact message with personal_sign / signMessage, validate its domain against the API origin, wallet address, verification URI, chain 421614, login-only purpose, and five-minute lifetime. Submit the challengeId and signature to POST /agents/auth/verify. Login does not authorize spending or require a funded wallet.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chainId": { "type": "integer", "enum": [ 421614 ] } }, "required": [ "address", "chainId" ] } } } }, "responses": { "200": { "description": "Successful wallet authentication operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "The agent does not own the resource", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Too many login attempts; wait one minute." }, "503": { "description": "Contract wallet verification temporarily unavailable." } } } }, "/agents/auth/verify": { "post": { "tags": [ "Agents" ], "operationId": "verifyWalletLogin", "summary": "Consume the one-time wallet proof and create or recover the agent", "description": "Consume the one-time wallet proof and create or recover the agent. Returns a one-hour bearer session. Supports EOAs and deployed ERC-1271 wallets; undeployed smart wallets are not supported.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "description": "Use data.challengeId from POST /agents/auth/challenge; do not generate this value." }, "signature": { "type": "string", "description": "Hex EIP-191 personal_sign signature of the exact data.message returned by POST /agents/auth/challenge. Accepts hex with or without a 0x prefix, including Python bytes.hex() output. The server normalizes the prefix before cryptographic verification.", "pattern": "^(0[xX])?([0-9a-fA-F]{2}){1,8192}$", "minLength": 2, "maxLength": 16386 }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional agent display name. Omit when unavailable; do not send null or an empty string." } }, "required": [ "challengeId", "signature" ] } } } }, "responses": { "200": { "description": "Successful wallet authentication operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "The agent does not own the resource", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Too many login attempts; wait one minute." }, "503": { "description": "Contract wallet verification temporarily unavailable." } } } }, "/agents/me": { "get": { "tags": [ "Agents" ], "operationId": "getCurrentAgent", "summary": "Read the authenticated wallet identity", "security": [ { "AgentSession": [] } ], "responses": { "200": { "description": "Authenticated agent", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agents/auth/logout": { "post": { "tags": [ "Agents" ], "operationId": "logoutAgent", "summary": "Revoke this wallet session", "security": [ { "AgentSession": [] } ], "responses": { "204": { "description": "Session revoked" }, "401": { "description": "Missing, expired, or revoked wallet session", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "AgentSession": { "type": "http", "scheme": "bearer", "description": "Opaque wallet session from POST /agents/auth/verify. Sign the server challenge once with your existing EVM wallet." } } } }