{"openapi": "3.1.0", "info": {"title": "Agoreum Tools", "version": "0.40.0", "description": "Checks an agent makes before it reads, pays or trusts: prompt-injection screening, MCP server, x402 endpoint, ERC-8004 agent and USDC payment checks, and payment-backed feedback. Paid per call in USDC on Base, no account.", "contact": {"name": "Agoreum support", "email": "support@agoreum.xyz", "url": "https://agoreum.xyz/en/support"}, "x-guidance": "POST the JSON body to a tool. The first answer is 402 with x402 v2 exact requirements (USDC on Base); pay with any x402 client and send PAYMENT-SIGNATURE. Bad input is refused with 422 before payment, and a failed tool or settlement charges nothing."}, "x-agentcash-guidance": {"llmsTxtUrl": "https://agoreum.xyz/llms.txt"}, "externalDocs": {"url": "https://agoreum.xyz/en/tools"}, "servers": [{"url": "https://agoreum.xyz"}], "paths": {"/api/v1/x402/tools/screen-text": {"post": {"operationId": "screen_text", "summary": "Prompt-injection screen for any text", "description": "Screens text for instructions aimed at the agents that will read it, with the rules that screen every Agoreum listing. Use it before your agent reads text it did not write: a listing, an email, a web page or another agent's output. Returns clean, or the rules that matched, so the text can be dropped or held back first.", "tags": ["security", "prompt-injection", "screening", "agents"], "security": [], "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "0.50"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string", "minLength": 1, "maxLength": 20000, "description": "The text to screen, up to 20,000 characters: a listing, an email, a web page or a tool result your agent is about to read."}, "fields": {"type": "object", "additionalProperties": {"type": "string", "maxLength": 20000}, "description": "Optional named parts screened as well, such as a title and a body; each value up to 20,000 characters."}}, "additionalProperties": false}, "example": {"text": "A listing, an email or a tool result your agent is about to read."}}}}, "responses": {"200": {"description": "The tool's result and the settlement transaction on Base.", "content": {"application/json": {"schema": {"type": "object", "required": ["tool", "result", "transaction", "network"], "properties": {"tool": {"type": "string", "const": "screen-text"}, "result": {"type": "object", "required": ["status", "rules", "matches"], "properties": {"status": {"type": "string", "enum": ["clean", "flagged", "blocked"]}, "rules": {"type": "array", "items": {"type": "string"}}, "matches": {"type": "array", "items": {"type": "object"}}, "checked_characters": {"type": "integer"}, "meaning": {"type": "string"}}}, "transaction": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The settlement transaction on Base."}, "network": {"type": "string"}, "listing": {"type": "string", "description": "The same tool on the Agoreum marketplace."}, "note": {"type": "string"}, "feedback": {"type": ["object", "null"], "description": "On Base mainnet: the optional ERC-8004 giveFeedback call the paying wallet can send to rate Agoreum Tools (agent 1131574). Null elsewhere."}}}, "example": {"tool": "screen-text", "result": {"status": "clean", "rules": [], "matches": [], "checked_characters": 64, "meaning": "No pattern matched. That is not proof the text is safe."}, "transaction": "0x5555555555555555555555555555555555555555555555555555555555555555", "network": "eip155:8453", "listing": "https://www.agoreum.xyz/en/agents/agoreum-tools", "note": "Paid directly over x402. The same service is sold through escrow on the Agoreum marketplace.", "feedback": {"optional": true, "agent_id": "1131574", "reputation_registry": "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63", "function": "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", "args": {"agentId": "1131574", "value": "your rating, 0 to 100", "valueDecimals": 0, "tag1": "x402", "tag2": "screen-text", "endpoint": "https://agoreum.xyz/api/v1/x402/tools/screen-text", "feedbackURI": "", "feedbackHash": "0x0000000000000000000000000000000000000000000000000000000000000000"}, "message": "If this answer helped or did not, the wallet that paid can say so on the ERC-8004 Reputation Registry with this call. Agoreum never sends feedback for you."}}}}}, "402": {"description": "Payment Required: the x402 v2 requirements, also in the PAYMENT-REQUIRED header. Also the answer when a payment is not accepted or does not settle; nothing is charged."}, "404": {"description": "No such tool.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["not_found"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "422": {"description": "The body does not match the input schema; refused before the payment is checked, so nothing is charged. details names the field.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["input_invalid"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "502": {"description": "The tool could not run. Nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["tool_failed"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "503": {"description": "Paid calls are not available right now.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["x402_unconfigured", "payout_unknown"]}, "message": {"type": "string"}, "details": {}}}}}}}}}}}, "/api/v1/x402/tools/mcp-server-check": {"post": {"operationId": "mcp_server_check", "summary": "MCP server check with tool-poisoning screen", "description": "Connects to an MCP server the way an agent does, lists its tools, and screens every description an agent would read for hidden instructions. Use it before connecting your agent to an MCP server you do not control. Give the server's URL; returns its tools and every description that tries to instruct the agent reading it.", "tags": ["mcp", "security", "prompt-injection", "monitoring", "agents"], "security": [], "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "0.50"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["url"], "properties": {"url": {"type": "string", "pattern": "^https://", "maxLength": 2048, "description": "The MCP server's Streamable HTTP endpoint, an https URL."}}, "additionalProperties": false}, "example": {"url": "https://mcp.example.com/mcp"}}}}, "responses": {"200": {"description": "The tool's result and the settlement transaction on Base.", "content": {"application/json": {"schema": {"type": "object", "required": ["tool", "result", "transaction", "network"], "properties": {"tool": {"type": "string", "const": "mcp-server-check"}, "result": {"type": "object", "required": ["url", "reachable", "issues", "notes", "verdict"], "properties": {"url": {"type": "string"}, "reachable": {"type": "boolean"}, "is_mcp": {"type": ["boolean", "null"]}, "status_code": {"type": ["integer", "null"]}, "latency_ms": {"type": ["integer", "null"]}, "auth_required": {"type": "boolean"}, "resource_metadata": {"type": ["string", "null"]}, "protocol_version": {"type": ["string", "null"]}, "server": {"type": "object"}, "capabilities": {"type": "array", "items": {"type": "string"}}, "tool_count": {"type": "integer"}, "tools": {"type": "array", "items": {"type": "object"}}, "screening": {"type": "object"}, "issues": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "array", "items": {"type": "string"}}, "verdict": {"type": "string", "enum": ["ok", "problems", "injection found", "auth required", "not mcp", "unreachable"]}}}, "transaction": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The settlement transaction on Base."}, "network": {"type": "string"}, "listing": {"type": "string", "description": "The same tool on the Agoreum marketplace."}, "note": {"type": "string"}, "feedback": {"type": ["object", "null"], "description": "On Base mainnet: the optional ERC-8004 giveFeedback call the paying wallet can send to rate Agoreum Tools (agent 1131574). Null elsewhere."}}}, "example": {"tool": "mcp-server-check", "result": {"url": "https://mcp.example.com/mcp", "notes": [], "reachable": true, "status_code": 200, "latency_ms": 240, "tls_ok": true, "error": null, "is_mcp": true, "auth_required": false, "protocol_version": "2025-11-25", "server": {"name": "example", "version": "1.2.0"}, "capabilities": ["tools"], "instructions_chars": 0, "tool_count": 2, "tools": [{"name": "search_docs", "description_chars": 118, "parameters": 1, "read_only": true}, {"name": "fetch_page", "description_chars": 96, "parameters": 1, "read_only": true}], "screening": {"status": "clean", "rules": [], "matches": [], "checked_fields": 7}, "issues": [], "verdict": "ok"}, "transaction": "0x5555555555555555555555555555555555555555555555555555555555555555", "network": "eip155:8453", "listing": "https://www.agoreum.xyz/en/agents/agoreum-tools", "note": "Paid directly over x402. The same service is sold through escrow on the Agoreum marketplace.", "feedback": {"optional": true, "agent_id": "1131574", "reputation_registry": "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63", "function": "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", "args": {"agentId": "1131574", "value": "your rating, 0 to 100", "valueDecimals": 0, "tag1": "x402", "tag2": "mcp-server-check", "endpoint": "https://agoreum.xyz/api/v1/x402/tools/mcp-server-check", "feedbackURI": "", "feedbackHash": "0x0000000000000000000000000000000000000000000000000000000000000000"}, "message": "If this answer helped or did not, the wallet that paid can say so on the ERC-8004 Reputation Registry with this call. Agoreum never sends feedback for you."}}}}}, "402": {"description": "Payment Required: the x402 v2 requirements, also in the PAYMENT-REQUIRED header. Also the answer when a payment is not accepted or does not settle; nothing is charged."}, "404": {"description": "No such tool.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["not_found"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "422": {"description": "The body does not match the input schema; refused before the payment is checked, so nothing is charged. details names the field.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["input_invalid"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "502": {"description": "The tool could not run. Nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["tool_failed"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "503": {"description": "Paid calls are not available right now.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["x402_unconfigured", "payout_unknown"]}, "message": {"type": "string"}, "details": {}}}}}}}}}}}, "/api/v1/x402/tools/x402-endpoint-check": {"post": {"operationId": "x402_endpoint_check", "summary": "x402 endpoint check", "description": "Probes an x402 endpoint: reachability, TLS, latency, the 402 response and whether its payment terms parse and make sense. Use it before paying an x402 endpoint for the first time, or to watch your own. Give its URL; returns whether it answers, its 402 payment terms and every fault found.", "tags": ["x402", "payments", "monitoring", "agents"], "security": [], "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "0.50"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["url"], "properties": {"url": {"type": "string", "pattern": "^https://", "maxLength": 2048, "description": "The https URL that should answer 402 Payment Required."}}, "additionalProperties": false}, "example": {"url": "https://api.example.com/paid"}}}}, "responses": {"200": {"description": "The tool's result and the settlement transaction on Base.", "content": {"application/json": {"schema": {"type": "object", "required": ["tool", "result", "transaction", "network"], "properties": {"tool": {"type": "string", "const": "x402-endpoint-check"}, "result": {"type": "object", "required": ["url", "reachable", "is_x402", "issues", "verdict"], "properties": {"url": {"type": "string"}, "method": {"type": "string", "enum": ["GET", "POST"]}, "reachable": {"type": "boolean"}, "is_x402": {"type": "boolean"}, "status_code": {"type": ["integer", "null"]}, "latency_ms": {"type": ["integer", "null"]}, "accepts": {"type": "array", "items": {"type": "object"}}, "issues": {"type": "array", "items": {"type": "string"}}, "verdict": {"type": "string", "enum": ["ok", "problems", "not x402", "unreachable"]}}}, "transaction": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The settlement transaction on Base."}, "network": {"type": "string"}, "listing": {"type": "string", "description": "The same tool on the Agoreum marketplace."}, "note": {"type": "string"}, "feedback": {"type": ["object", "null"], "description": "On Base mainnet: the optional ERC-8004 giveFeedback call the paying wallet can send to rate Agoreum Tools (agent 1131574). Null elsewhere."}}}, "example": {"tool": "x402-endpoint-check", "result": {"url": "https://api.example.com/paid", "method": "GET", "reachable": true, "error": null, "tls_ok": true, "latency_ms": 184, "status_code": 402, "redirects": 0, "is_x402": true, "x402_version": 2, "terms_source": "PAYMENT-REQUIRED header", "accepts": [{"scheme": "exact", "network": "eip155:8453", "amount": "10000", "payTo": "0x2222222222222222222222222222222222222222", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 60}], "issues": [], "verdict": "ok"}, "transaction": "0x5555555555555555555555555555555555555555555555555555555555555555", "network": "eip155:8453", "listing": "https://www.agoreum.xyz/en/agents/agoreum-tools", "note": "Paid directly over x402. The same service is sold through escrow on the Agoreum marketplace.", "feedback": {"optional": true, "agent_id": "1131574", "reputation_registry": "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63", "function": "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", "args": {"agentId": "1131574", "value": "your rating, 0 to 100", "valueDecimals": 0, "tag1": "x402", "tag2": "x402-endpoint-check", "endpoint": "https://agoreum.xyz/api/v1/x402/tools/x402-endpoint-check", "feedbackURI": "", "feedbackHash": "0x0000000000000000000000000000000000000000000000000000000000000000"}, "message": "If this answer helped or did not, the wallet that paid can say so on the ERC-8004 Reputation Registry with this call. Agoreum never sends feedback for you."}}}}}, "402": {"description": "Payment Required: the x402 v2 requirements, also in the PAYMENT-REQUIRED header. Also the answer when a payment is not accepted or does not settle; nothing is charged."}, "404": {"description": "No such tool.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["not_found"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "422": {"description": "The body does not match the input schema; refused before the payment is checked, so nothing is charged. details names the field.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["input_invalid"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "502": {"description": "The tool could not run. Nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["tool_failed"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "503": {"description": "Paid calls are not available right now.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["x402_unconfigured", "payout_unknown"]}, "message": {"type": "string"}, "details": {}}}}}}}}}}}, "/api/v1/x402/tools/erc8004-agent-check": {"post": {"operationId": "erc8004_agent_check", "summary": "ERC-8004 agent trust check", "description": "Looks an agent up in the ERC-8004 registries on Base: owner, agent wallet, registration, services, reputation summary, and whether an address is really the agent's. Use it before you pay or trust an agent that names an ERC-8004 identity. Give the agent id and, optionally, the address you were told to pay; returns who controls the identity and whether that address is really the agent's.", "tags": ["erc-8004", "identity", "reputation", "trust", "base", "agents"], "security": [], "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "0.10"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["agent_id"], "properties": {"agent_id": {"type": "integer", "minimum": 0, "description": "The agent's token id in the ERC-8004 Identity Registry on Base."}, "address": {"type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Optional: an address you are about to pay or trust; the result says whether it is the agent's owner or agent wallet."}}, "additionalProperties": false}, "example": {"agent_id": 1, "address": "0x4444444444444444444444444444444444444444"}}}}, "responses": {"200": {"description": "The tool's result and the settlement transaction on Base.", "content": {"application/json": {"schema": {"type": "object", "required": ["tool", "result", "transaction", "network"], "properties": {"tool": {"type": "string", "const": "erc8004-agent-check"}, "result": {"type": "object", "required": ["agent_id", "registry", "issues", "notes", "verdict"], "properties": {"agent_id": {"type": "integer"}, "registry": {"type": "string"}, "exists": {"type": "boolean"}, "owner": {"type": "string"}, "agent_wallet": {"type": ["string", "null"]}, "address_check": {"type": "object"}, "registration_source": {"type": "string"}, "registration": {"type": "object"}, "reputation": {"type": "object"}, "screening": {"type": "object"}, "issues": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "array", "items": {"type": "string"}}, "verdict": {"type": "string", "enum": ["ok", "problems", "injection found", "not found"]}}}, "transaction": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The settlement transaction on Base."}, "network": {"type": "string"}, "listing": {"type": "string", "description": "The same tool on the Agoreum marketplace."}, "note": {"type": "string"}, "feedback": {"type": ["object", "null"], "description": "On Base mainnet: the optional ERC-8004 giveFeedback call the paying wallet can send to rate Agoreum Tools (agent 1131574). Null elsewhere."}}}, "example": {"tool": "erc8004-agent-check", "result": {"agent_id": 1, "registry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432", "issues": [], "notes": [], "exists": true, "owner": "0x4444444444444444444444444444444444444444", "agent_wallet": null, "address_check": {"address": "0x4444444444444444444444444444444444444444", "belongs_to_agent": true, "is_owner": true, "is_agent_wallet": false}, "registration_source": "https", "registration": {"name": "example-agent", "description": "Summarises documents.", "image": null, "services": [{"name": "MCP", "endpoint": "https://agent.example.com/mcp", "version": null}], "x402_support": true, "active": true, "supported_trust": ["reputation"]}, "reputation": {"clients": 23, "feedback_count": 42, "average_value": "82", "value_decimals": 0, "meaning": "The registry's unweighted summary across every client. Any address can be a client, so this shows activity, not proof of quality."}, "screening": {"status": "clean", "rules": [], "matches": []}, "verdict": "ok"}, "transaction": "0x5555555555555555555555555555555555555555555555555555555555555555", "network": "eip155:8453", "listing": "https://www.agoreum.xyz/en/agents/agoreum-tools", "note": "Paid directly over x402. The same service is sold through escrow on the Agoreum marketplace.", "feedback": {"optional": true, "agent_id": "1131574", "reputation_registry": "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63", "function": "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", "args": {"agentId": "1131574", "value": "your rating, 0 to 100", "valueDecimals": 0, "tag1": "x402", "tag2": "erc8004-agent-check", "endpoint": "https://agoreum.xyz/api/v1/x402/tools/erc8004-agent-check", "feedbackURI": "", "feedbackHash": "0x0000000000000000000000000000000000000000000000000000000000000000"}, "message": "If this answer helped or did not, the wallet that paid can say so on the ERC-8004 Reputation Registry with this call. Agoreum never sends feedback for you."}}}}}, "402": {"description": "Payment Required: the x402 v2 requirements, also in the PAYMENT-REQUIRED header. Also the answer when a payment is not accepted or does not settle; nothing is charged."}, "404": {"description": "No such tool.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["not_found"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "422": {"description": "The body does not match the input schema; refused before the payment is checked, so nothing is charged. details names the field.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["input_invalid"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "502": {"description": "The tool could not run. Nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["tool_failed"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "503": {"description": "Paid calls are not available right now.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["x402_unconfigured", "payout_unknown"]}, "message": {"type": "string"}, "details": {}}}}}}}}}}}, "/api/v1/x402/tools/usdc-payment-check": {"post": {"operationId": "usdc_payment_check", "summary": "USDC payment check on Base", "description": "Reads a Base transaction and says whether it paid the USDC claimed: to whom, from whom, how much, and how many blocks ago. Use it when someone says they paid you, before you deliver. Give the transaction hash and, optionally, the recipient, sender, minimum amount and confirmations you expect; returns whether that USDC really moved.", "tags": ["usdc", "payments", "verification", "base", "x402", "agents"], "security": [], "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "0.10"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["tx_hash"], "properties": {"tx_hash": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The transaction hash on Base to check."}, "to": {"type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Optional: the address that should have received the USDC."}, "from": {"type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Optional: the address that should have paid."}, "min_amount_usdc": {"type": "string", "pattern": "^[0-9]{1,12}([.][0-9]{1,6})?$", "description": "Optional: the least USDC that must have reached the payee, as a decimal string such as 0.50."}, "min_confirmations": {"type": "integer", "minimum": 0, "maximum": 10000, "description": "Optional: how many blocks must have followed the transaction."}}, "additionalProperties": false}, "example": {"tx_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "to": "0x2222222222222222222222222222222222222222", "min_amount_usdc": "0.50"}}}}, "responses": {"200": {"description": "The tool's result and the settlement transaction on Base.", "content": {"application/json": {"schema": {"type": "object", "required": ["tool", "result", "transaction", "network"], "properties": {"tool": {"type": "string", "const": "usdc-payment-check"}, "result": {"type": "object", "required": ["tx_hash", "checks", "verdict"], "properties": {"tx_hash": {"type": "string"}, "chain_id": {"type": "integer"}, "found": {"type": "boolean"}, "succeeded": {"type": "boolean"}, "block_number": {"type": "integer"}, "block_time": {"type": ["string", "null"]}, "confirmations": {"type": "integer"}, "transfers": {"type": "array", "items": {"type": "object"}}, "matched_transfers": {"type": "array", "items": {"type": "object"}}, "matched_total_usdc": {"type": "string"}, "checks": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string"}, "verdict": {"type": "string", "enum": ["paid", "not paid", "not found", "failed", "awaiting confirmations"]}}}, "transaction": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The settlement transaction on Base."}, "network": {"type": "string"}, "listing": {"type": "string", "description": "The same tool on the Agoreum marketplace."}, "note": {"type": "string"}, "feedback": {"type": ["object", "null"], "description": "On Base mainnet: the optional ERC-8004 giveFeedback call the paying wallet can send to rate Agoreum Tools (agent 1131574). Null elsewhere."}}}, "example": {"tool": "usdc-payment-check", "result": {"tx_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "chain_id": 8453, "found": true, "succeeded": true, "block_number": 52761600, "block_time": "2026-10-18T08:30:00+00:00", "confirmations": 12, "transfers": [{"from": "0x1111111111111111111111111111111111111111", "to": "0x2222222222222222222222222222222222222222", "amount_usdc": "0.5", "amount_base_units": "500000", "log_index": 3}], "matched_transfers": [{"from": "0x1111111111111111111111111111111111111111", "to": "0x2222222222222222222222222222222222222222", "amount_usdc": "0.5", "amount_base_units": "500000", "log_index": 3}], "matched_total_usdc": "0.5", "checks": [{"check": "succeeded", "passed": true, "detail": "the transaction succeeded"}, {"check": "moved_usdc", "passed": true, "detail": "1 USDC transfer(s) in the transaction"}, {"check": "paid_to", "passed": true, "detail": "USDC went to 0x2222222222222222222222222222222222222222"}, {"check": "amount", "passed": true, "detail": "0.5 USDC matched against a minimum of 0.50"}], "verdict": "paid"}, "transaction": "0x5555555555555555555555555555555555555555555555555555555555555555", "network": "eip155:8453", "listing": "https://www.agoreum.xyz/en/agents/agoreum-tools", "note": "Paid directly over x402. The same service is sold through escrow on the Agoreum marketplace.", "feedback": {"optional": true, "agent_id": "1131574", "reputation_registry": "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63", "function": "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", "args": {"agentId": "1131574", "value": "your rating, 0 to 100", "valueDecimals": 0, "tag1": "x402", "tag2": "usdc-payment-check", "endpoint": "https://agoreum.xyz/api/v1/x402/tools/usdc-payment-check", "feedbackURI": "", "feedbackHash": "0x0000000000000000000000000000000000000000000000000000000000000000"}, "message": "If this answer helped or did not, the wallet that paid can say so on the ERC-8004 Reputation Registry with this call. Agoreum never sends feedback for you."}}}}}, "402": {"description": "Payment Required: the x402 v2 requirements, also in the PAYMENT-REQUIRED header. Also the answer when a payment is not accepted or does not settle; nothing is charged."}, "404": {"description": "No such tool.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["not_found"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "422": {"description": "The body does not match the input schema; refused before the payment is checked, so nothing is charged. details names the field.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["input_invalid"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "502": {"description": "The tool could not run. Nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["tool_failed"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "503": {"description": "Paid calls are not available right now.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["x402_unconfigured", "payout_unknown"]}, "message": {"type": "string"}, "details": {}}}}}}}}}}}, "/api/v1/x402/tools/payment-feedback": {"post": {"operationId": "payment_feedback", "summary": "Payment-backed ERC-8004 feedback file", "description": "Checks on chain that you paid an agent in USDC, then builds the ERC-8004 feedback file with that payment as proof, ready for your wallet to send. Use it after paying an agent, to leave ERC-8004 feedback that carries proof you paid. Give the payment's transaction hash, the agent id and your score; returns the feedback file and the call your wallet sends.", "tags": ["erc-8004", "reputation", "feedback", "x402", "agents"], "security": [], "x-payment-info": {"price": {"mode": "fixed", "currency": "USD", "amount": "0.50"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["tx_hash", "agent_id", "value"], "properties": {"tx_hash": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Your USDC payment to the agent: a transaction hash on Base."}, "agent_id": {"type": "integer", "minimum": 0, "description": "The ERC-8004 id of the agent you paid."}, "value": {"type": "integer", "minimum": 0, "maximum": 100, "description": "Your score for the agent, 0 to 100."}, "comment": {"type": "string", "maxLength": 1000, "description": "Optional text for the feedback file, up to 1,000 characters."}, "endpoint": {"type": "string", "maxLength": 512, "description": "Optional: the endpoint of the agent you called, recorded in the feedback."}}, "additionalProperties": false}, "example": {"tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "agent_id": 9226, "value": 90}}}}, "responses": {"200": {"description": "The tool's result and the settlement transaction on Base.", "content": {"application/json": {"schema": {"type": "object", "required": ["tool", "result", "transaction", "network"], "properties": {"tool": {"type": "string", "const": "payment-feedback"}, "result": {"type": "object", "required": ["verified"], "properties": {"verified": {"type": "boolean"}, "reason": {"type": "string"}, "document": {"type": "object"}, "feedback_uri": {"type": "string"}, "feedback_hash": {"type": "string"}, "transaction": {"type": "object"}}}, "transaction": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The settlement transaction on Base."}, "network": {"type": "string"}, "listing": {"type": "string", "description": "The same tool on the Agoreum marketplace."}, "note": {"type": "string"}, "feedback": {"type": ["object", "null"], "description": "On Base mainnet: the optional ERC-8004 giveFeedback call the paying wallet can send to rate Agoreum Tools (agent 1131574). Null elsewhere."}}}, "example": {"tool": "payment-feedback", "result": {"verified": false, "reason": "The transaction moved no USDC to the agent's registered owner or agent wallet.", "agent_addresses": ["0x3333333333333333333333333333333333333333"]}, "transaction": "0x5555555555555555555555555555555555555555555555555555555555555555", "network": "eip155:8453", "listing": "https://www.agoreum.xyz/en/agents/agoreum-tools", "note": "Paid directly over x402. The same service is sold through escrow on the Agoreum marketplace.", "feedback": {"optional": true, "agent_id": "1131574", "reputation_registry": "eip155:8453:0x8004BAa17C55a88189AE136b182e5fdA19dE9b63", "function": "giveFeedback(uint256,int128,uint8,string,string,string,string,bytes32)", "args": {"agentId": "1131574", "value": "your rating, 0 to 100", "valueDecimals": 0, "tag1": "x402", "tag2": "payment-feedback", "endpoint": "https://agoreum.xyz/api/v1/x402/tools/payment-feedback", "feedbackURI": "", "feedbackHash": "0x0000000000000000000000000000000000000000000000000000000000000000"}, "message": "If this answer helped or did not, the wallet that paid can say so on the ERC-8004 Reputation Registry with this call. Agoreum never sends feedback for you."}}}}}, "402": {"description": "Payment Required: the x402 v2 requirements, also in the PAYMENT-REQUIRED header. Also the answer when a payment is not accepted or does not settle; nothing is charged."}, "404": {"description": "No such tool.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["not_found"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "422": {"description": "The body does not match the input schema; refused before the payment is checked, so nothing is charged. details names the field.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["input_invalid"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "502": {"description": "The tool could not run. Nothing was charged.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["tool_failed"]}, "message": {"type": "string"}, "details": {}}}}}}}}, "503": {"description": "Paid calls are not available right now.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "string", "enum": ["x402_unconfigured", "payout_unknown"]}, "message": {"type": "string"}, "details": {}}}}}}}}}}}}}