{"openapi":"3.1.0","info":{"title":"Arc ERC-8004 Explorer API","version":"1.4.0","description":"Read-only public API for resolving ERC-8004 agent identities on Arc Mainnet. Paid x402 endpoint only. No write operations.","contact":{"url":"https://www.arcagents.app","email":"hi@arcagents.app"},"x-agent-consumable":true,"x-guidance":"ARC AGENTS API — guidance for AI agents\n\nSERVICE: Resolve ERC-8004 on-chain agent identities registered on the Arc blockchain.\nReturns: owner address, agent wallet, IPFS metadata (name, description, services), reputation score and client feedback, and validation status.\n\nENDPOINT — GET /api/agent/paid\n  Required: network=mainnet, agentId (positive integer)\n  Cost: 0.002 USDC per successful request (2000 atomic units, 6 decimals)\n  Payment: x402 Version 2, scheme \"exact\" (EIP-3009 transferWithAuthorization), verified and settled by the Ultravioleta DAO facilitator. USDC is paid directly to the seller address in payTo.\n  Accepted payment networks (payer's choice — ERC-8004 data always comes from Arc Mainnet):\n    • Arc Mainnet  — eip155:5042 — USDC 0x3600000000000000000000000000000000000000 (EIP-712 domain: name \"USDC\", version \"2\"; amount = 2000)\n    • Base Mainnet — eip155:8453 — USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (EIP-712 domain: name \"USD Coin\", version \"2\"; amount = 2000)\n  The EIP-712 domain name differs per network; copy accepts[].extra.name and accepts[].extra.version from the chosen entry.\n  Flow: 1) Send GET without PAYMENT-SIGNATURE → receive 402 with PAYMENT-REQUIRED header.\n         2) Decode PAYMENT-REQUIRED (base64 JSON) — accepts[] lists both networks.\n         3) Choose one payment network. Sign an EIP-3009 authorization for 2000 USDC units on that network.\n         4) Base64-encode the signed payload → PAYMENT-SIGNATURE header.\n         5) Resend GET with PAYMENT-SIGNATURE → receive 200 AgentResponse and a PAYMENT-RESPONSE header on success.\n  A 404 or a 503 rpc_error is returned before settlement and is never charged. Payment verification and settlement are done by the Ultravioleta DAO facilitator through its official SDK; answers use the SDK formats. 402 {error: Payment verification failed} = the facilitator refused the payment. 503 (Retry-After) = no final result yet (verification unavailable, authorization in flight, settlement pending or ambiguous): do NOT sign a new payment; resend the IDENTICAL request with the same signed payment (and the same X-UVD-Purchase if you sent one). 409 = the authorization was already used or belongs to another purchase. 500 {error: Payment settlement failed} = settlement failed or could not be confirmed; any transaction hash is in the body. A settlement problem is never a new 402 challenge.\n  Returns: AgentResponse (identity, metadata, reputation, validation).\n  Mainnet only: network=testnet returns 400.\n\nWHEN TO CALL:\n  - Call /api/agent/paid to resolve ERC-8004 agent identity, metadata, reputation, and validation data.\n  - The endpoint is read-only and safe to call without fear of side effects.\n\nDISCOVERY: the 402 challenge carries Bazaar metadata (extensions.bazaar). Third-party catalogues (a listing is not proof of a completed live payment):\n  Ultravioleta DAO Bazaar: https://facilitator.ultravioletadao.xyz/bazaar?q=www.arcagents.app\n  x402 Bazaar: https://x402-bazaar.com/resources/6af36d3129802b0f3634caf5\n\nAGENT IDs: on Arc Mainnet, confirmed agents include #1, #8, #14, #15.\nA 404 means the agent ID is not minted on Arc Mainnet."},"externalDocs":{"description":"Arc ERC-8004 Explorer","url":"https://www.arcagents.app"},"servers":[{"url":"https://www.arcagents.app","description":"Production (also the x402 payment resource host: the 402 challenge resource.url)"}],"paths":{"/api/agent/paid":{"get":{"operationId":"getAgentPaid","summary":"Retrieve ERC-8004 agent data from Arc Mainnet (paid, 0.002 USDC)","description":"Retrieve ERC-8004 agent identity and registration data from Arc Mainnet through x402 v2 payments. Returns identity, metadata, reputation, and validation data for one agent ID. Requires an x402 v2 \"exact\" payment of 0.002 USDC (2000 atomic units) verified and settled by the Ultravioleta DAO facilitator, paid directly to the seller address. ERC-8004 data is always resolved from Arc Mainnet (network=mainnet). Payment can be made on either of two networks: Arc Mainnet (eip155:5042, USDC 0x3600000000000000000000000000000000000000) or Base Mainnet (eip155:8453, USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). The 402 response lists both networks in accepts[] and carries Bazaar discovery metadata in extensions.bazaar. Only network=mainnet is accepted as the ERC-8004 data network. Requires a PAYMENT-SIGNATURE header containing a base64-encoded x402 Version 2 payment payload; a successful response includes a PAYMENT-RESPONSE header with the settlement transaction.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"X-UVD-Purchase","in":"header","required":false,"description":"Optional purchase context for recovering a lost or uncertain settlement (Ultravioleta SDK fetchWithReceipt): base64 JSON {purchaseId, accessToken, method, url, bodySha256} bound to this exact GET request (full URL including network and agentId, empty body). Send it with PAYMENT-SIGNATURE and resend it unchanged on retries. A context that does not match the request returns 400 receipt_context_mismatch.","schema":{"type":"string","maxLength":8192}},{"name":"network","in":"query","required":true,"description":"Must be 'mainnet'. The paid endpoint resolves ERC-8004 data from Arc Mainnet only.","schema":{"type":"string","enum":["mainnet"]},"example":"mainnet"},{"name":"agentId","in":"query","required":true,"description":"ERC-8004 agent token ID (positive integer).","schema":{"type":"integer","minimum":1},"example":15}],"responses":{"200":{"description":"Agent resolved successfully. Payment was settled.","headers":{"Access-Control-Allow-Origin":{"description":"CORS header. Always *.","schema":{"type":"string"}},"Cache-Control":{"description":"no-store — paid responses are never cached.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid or missing query parameters, network=testnet was requested, or X-UVD-Purchase does not match the request (error: receipt_context_mismatch).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required or payment rejected. The PAYMENT-REQUIRED header contains a base64-encoded x402 Version 2 payment requirements object that also carries the Bazaar discovery metadata in extensions.bazaar (abbreviated in the example below). When a submitted payment is malformed, does not match an accepted option, or is refused at verification, the body is an error (payment_invalid, or Payment verification failed with the facilitator reason) and the PAYMENT-REQUIRED header is still returned. A settlement failure is never a 402.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded JSON payment requirements (x402 Version 2). Decode to read accepts[], which lists two payment options: Arc Mainnet (eip155:5042) and Base Mainnet (eip155:8453). Choose one, sign an EIP-3009 authorization for 2000 USDC units on that network using the EIP-712 domain in accepts[].extra, base64-encode the payload, and resend as the PAYMENT-SIGNATURE header.","schema":{"type":"string","format":"byte"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"},"example":{"x402Version":2,"resource":{"url":"https://www.arcagents.app/api/agent/paid","description":"Retrieve ERC-8004 agent identity and registration data from Arc Mainnet through x402 v2 payments.","mimeType":"application/json","serviceName":"Arc ERC-8004 Explorer","tags":["arc","erc-8004","agents","blockchain","identity"],"iconUrl":"https://www.arcagents.app/icon-512.png"},"accepts":[{"scheme":"exact","network":"eip155:5042","asset":"0x3600000000000000000000000000000000000000","amount":"2000","payTo":"0x<SELLER_ADDRESS>","maxTimeoutSeconds":60,"extra":{"name":"USDC","version":"2"}},{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"2000","payTo":"0x<SELLER_ADDRESS>","maxTimeoutSeconds":60,"extra":{"name":"USD Coin","version":"2"}}],"extensions":{"bazaar":{"info":{"input":{"type":"http","method":"GET","queryParams":{"network":"mainnet","agentId":15}},"output":{"type":"json","example":"(AgentResponse example; see the PAYMENT-REQUIRED header)"}},"schema":"(JSON Schema for the query parameters and the AgentResponse output; see the PAYMENT-REQUIRED header)"}}}}}},"404":{"description":"Agent ID not found on Arc Mainnet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"error: Payment authorization already used (reason: authorization_already_settled), or Payment request conflict (reason: receipt_request_conflict): the authorization was used or admitted for a different purchase. No data is returned, nothing is settled again, retryable: false. Do not sign another payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error, or error: Payment settlement failed: settlement failed or could not be confirmed (retryable: false, no Retry-After; includes a 202 settlement_in_progress without a pending receipt and a receipt that is not confirmed). A failure the facilitator itself states also carries a PAYMENT-RESPONSE with success: false and its errorReason. No data is returned. Do not sign a new payment; any transaction hash, errorCode and paymentId are in the body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Not charged or not final. Before settlement: the RPC call failed (rpc_error), verification was unavailable (error: Payment verification unavailable), the authorization is in flight (reason: authorization_in_flight), or there was no time left to settle. After a settle attempt: error: Payment settlement unavailable (the SDK flagged the result retryable: pending or unknown receipt, timeout or lost connection, 429/503). Always with Retry-After and retryable: true. Do not sign a new payment; resend the identical request with the same signed payment (and the same X-UVD-Purchase if you sent one). No PAYMENT-RESPONSE is sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/openapi.json":{"get":{"operationId":"getOpenApi","summary":"OpenAPI specification","description":"Returns this OpenAPI 3.1 document.","security":[],"responses":{"200":{"description":"OpenAPI document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"AgentResponse":{"type":"object","required":["agentId","network","chainId","identity","metadata","metadataError","reputation","validation","links","fetchedAt"],"properties":{"agentId":{"type":"integer","description":"ERC-8004 token ID."},"network":{"type":"string","enum":["mainnet"]},"chainId":{"type":"integer","description":"EVM chain ID."},"identity":{"type":"object","properties":{"owner":{"type":"string","description":"Token owner address."},"agentWallet":{"type":"string","description":"Designated agent wallet address."},"metadataUri":{"type":"string","description":"Raw IPFS or HTTPS metadata URI."},"registries":{"type":"object","properties":{"identity":{"type":"string"},"reputation":{"type":"string"},"validation":{"type":["string","null"]}}}}},"metadata":{"type":["object","null"],"description":"Parsed agent metadata JSON. Null if IPFS fetch failed.","properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]},"services":{"type":["array","null"],"items":{"type":"object"}},"active":{"type":["boolean","null"]},"x402Support":{"type":["boolean","null"]}}},"metadataError":{"type":["string","null"],"description":"Error code if metadata fetch failed; null on success."},"reputation":{"type":"object","properties":{"clientCount":{"type":"integer"},"feedbackCount":{"type":"integer"},"aggregateScore":{"type":["string","null"]},"clients":{"type":"array","items":{"type":"string"}},"feedback":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackRecord"}}}},"validation":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"type":["string","null"]},"requestCount":{"type":["integer","null"]},"requests":{"type":"array","items":{"$ref":"#/components/schemas/ValidationRequest"}}}},"links":{"type":"object","properties":{"explorer":{"type":"string"},"agentOnExplorer":{"type":"string"}}},"fetchedAt":{"type":"string","format":"date-time"}}},"FeedbackRecord":{"type":"object","properties":{"client":{"type":"string"},"feedbackIndex":{"type":"integer"},"value":{"type":"string","description":"Formatted signed decimal score."},"tag1":{"type":["string","null"]},"tag2":{"type":["string","null"]},"isRevoked":{"type":"boolean"}}},"ValidationRequest":{"type":"object","properties":{"requestHash":{"type":"string"},"validatorAddress":{"type":"string"},"response":{"type":"integer"},"responseHash":{"type":"string"},"hasResponse":{"type":"boolean"},"tag":{"type":["string","null"]},"lastUpdate":{"type":"integer","description":"Unix timestamp."},"lastUpdateIso":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string"},"agentId":{"type":"integer"},"network":{"type":"string"},"chainId":{"type":"integer"}}},"PaymentRequiredResponse":{"type":"object","description":"x402 Version 2 payment requirements. Returned as the 402 body and in the base64-encoded PAYMENT-REQUIRED header. accepts[] contains one entry per supported payment network (Arc Mainnet eip155:5042 and Base Mainnet eip155:8453). ERC-8004 data is always resolved from Arc Mainnet regardless of which payment network is used.","properties":{"x402Version":{"type":"integer","enum":[2]},"error":{"type":"string","description":"Present when a submitted payment was rejected (payment_invalid or Payment verification failed)."},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"serviceName":{"type":"string","description":"Human-readable service name for catalogs."},"tags":{"type":"array","items":{"type":"string"},"description":"Short topical tags for discovery search."},"iconUrl":{"type":"string","description":"Absolute https URL of the service icon."}}},"accepts":{"type":"array","description":"List of accepted payment options, one per network: Arc Mainnet (eip155:5042) and Base Mainnet (eip155:8453). Choose one to pay with.","items":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","description":"CAIP-2 network ID. eip155:5042 = Arc Mainnet; eip155:8453 = Base Mainnet."},"asset":{"type":"string","description":"USDC contract address on the payment network. Arc Mainnet: 0x3600000000000000000000000000000000000000; Base Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913."},"amount":{"type":"string","description":"Payment amount in smallest USDC units (6 decimals). 2000 = 0.002 USDC."},"payTo":{"type":"string","description":"Seller's external EVM receive address. USDC is transferred here directly."},"maxTimeoutSeconds":{"type":"integer","description":"How long a signed authorization stays valid (60 seconds)."},"extra":{"type":"object","description":"EIP-712 domain of the USDC contract on this network, needed to sign the EIP-3009 authorization. It differs per network.","properties":{"name":{"type":"string","description":"Arc Mainnet: \"USDC\"; Base Mainnet: \"USD Coin\""},"version":{"type":"string","description":"EIP-712 domain version (\"2\" on both networks)."}}}}}},"extensions":{"type":"object","description":"x402 extensions. extensions.bazaar is the official Bazaar discovery declaration: info.input (HTTP GET with the query parameters network and agentId), info.output (a real example response), and a JSON Schema for both.","properties":{"bazaar":{"type":"object","description":"Bazaar discovery extension (info + schema)."}}}}}}}}