{"openapi":"3.0.3","info":{"title":"xproof ACP - Agent Commerce Protocol","description":"API for AI agents to certify files on MultiversX blockchain. Create immutable proofs of file ownership with a simple API call. Supports x402 payment protocol (HTTP 402) as an alternative to API key auth — send requests to POST /api/proof or POST /api/batch without an API key, receive 402 with payment requirements, sign payment in USDC on Base (eip155:8453), and resend with X-PAYMENT header.","version":"1.0.0","contact":{"name":"xproof Support","url":"https://provebeforeact.com"}},"servers":[{"url":"https://provebeforeact.com","description":"Production server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key in format: pm_xxx... Obtain from /api/keys endpoint"}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string","example":"xproof-certification"},"name":{"type":"string","example":"xproof Certification"},"description":{"type":"string"},"pricing":{"type":"object","properties":{"type":{"type":"string","enum":["fixed","variable"]},"amount":{"type":"string","example":"0.01"},"currency":{"type":"string","example":"USD"}}},"inputs":{"type":"object","additionalProperties":{"type":"string"}},"outputs":{"type":"object","additionalProperties":{"type":"string"}}}},"CheckoutRequest":{"type":"object","required":["product_id","inputs"],"properties":{"product_id":{"type":"string","example":"xproof-certification"},"inputs":{"type":"object","required":["file_hash","filename"],"properties":{"file_hash":{"type":"string","description":"SHA-256 hash of the file (64 hex chars)","example":"a1b2c3d4e5f678901234567890123456789012345678901234567890123456ab"},"filename":{"type":"string","example":"document.pdf"},"author_name":{"type":"string","example":"AI Agent"},"metadata":{"type":"object","description":"Optional JSON metadata. Supports model_hash, strategy_hash, version_number, and any custom fields. Searchable via GET /api/proofs/search.","properties":{"model_hash":{"type":"string"},"strategy_hash":{"type":"string"},"version_number":{"type":"string"}},"additionalProperties":true}}},"buyer":{"type":"object","properties":{"type":{"type":"string","enum":["agent","user"]},"id":{"type":"string"}}}}},"CheckoutResponse":{"type":"object","properties":{"checkout_id":{"type":"string","format":"uuid"},"product_id":{"type":"string"},"amount":{"type":"string","description":"Price in USD"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","ready"]},"execution":{"type":"object","properties":{"type":{"type":"string","example":"multiversx"},"mode":{"type":"string","enum":["direct","relayed_v3"]},"chain_id":{"type":"string","example":"1"},"tx_payload":{"type":"object","properties":{"receiver":{"type":"string","description":"xproof wallet address"},"data":{"type":"string","description":"Base64 encoded transaction data"},"value":{"type":"string","description":"EGLD amount in atomic units (1 EGLD = 10^18)"},"gas_limit":{"type":"integer","example":100000}}}}},"expires_at":{"type":"string","format":"date-time"}}},"ConfirmRequest":{"type":"object","required":["checkout_id","tx_hash"],"properties":{"checkout_id":{"type":"string","format":"uuid"},"tx_hash":{"type":"string","description":"MultiversX transaction hash"}}},"ConfirmResponse":{"type":"object","properties":{"status":{"type":"string","enum":["confirmed","pending","failed"]},"checkout_id":{"type":"string"},"tx_hash":{"type":"string"},"certification_id":{"type":"string"},"certificate_url":{"type":"string","format":"uri"},"proof_url":{"type":"string","format":"uri"},"blockchain_explorer_url":{"type":"string","format":"uri"},"message":{"type":"string"}}},"PaymentVerificationError":{"type":"object","description":"Returned (HTTP 402) when the payment cannot be verified. If retry is true, the network was unreachable and the caller should retry after retry_after_seconds, up to max_retries times.","properties":{"error":{"type":"string","example":"PAYMENT_VERIFICATION_FAILED"},"message":{"type":"string"},"retry":{"type":"boolean","description":"true when the failure is transient (network unreachable) and the same request may succeed later. false (or absent) when the payment was verified and rejected for a permanent reason."},"retry_after_seconds":{"type":"integer","example":15,"description":"Minimum seconds to wait before the next retry attempt. Present when retry is true."},"max_retries":{"type":"integer","example":5,"description":"Maximum number of consecutive retries before treating the failure as permanent. Present when retry is true."},"tx_status":{"type":"string","description":"The on-chain transaction status when it was found but not 'success' (e.g. 'pending', 'failed')."}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/acp/products":{"get":{"summary":"Discover available products","description":"Returns list of certification products available for purchase. No authentication required.","security":[],"responses":{"200":{"description":"List of products","content":{"application/json":{"schema":{"type":"object","properties":{"protocol":{"type":"string","example":"ACP"},"version":{"type":"string","example":"1.0"},"provider":{"type":"string","example":"xproof"},"chain":{"type":"string","example":"MultiversX"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}}}},"/api/acp/checkout":{"post":{"summary":"Create checkout session","description":"Initiate certification by providing file hash. Returns transaction payload for MultiversX signing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"201":{"description":"Checkout created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"401":{"description":"API key required"},"409":{"description":"File already certified"}}}},"/api/acp/confirm":{"post":{"summary":"Confirm transaction","description":"After signing and broadcasting transaction, confirm to receive certification ID and URLs. This endpoint is idempotent: if the checkout is already confirmed, re-submitting returns 200 with the existing certification data (safe to retry after a network timeout).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmRequest"}}}},"responses":{"200":{"description":"Certification confirmed (or idempotent re-submit of an already-confirmed checkout)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmResponse"}}}},"401":{"description":"API key required"},"402":{"description":"Payment could not be verified. If retry=true the network was unreachable — wait retry_after_seconds and retry up to max_retries times. If retry is absent or false, the payment was rejected for a permanent reason (wrong receiver, insufficient value, etc.) and a new checkout is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVerificationError"}}}},"404":{"description":"Checkout not found"},"410":{"description":"Checkout expired or displaced"}}}},"/api/acp/checkout/{checkoutId}":{"get":{"summary":"Get checkout status","description":"Check the status of an existing checkout session.","parameters":[{"name":"checkoutId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout status"},"404":{"description":"Checkout not found"}}}},"/mcp":{"post":{"summary":"MCP Server (JSON-RPC 2.0)","description":"Model Context Protocol server endpoint. Accepts JSON-RPC 2.0 requests over Streamable HTTP. Supports methods: initialize, tools/list, tools/call, resources/list, resources/read. Tools: register_trial (no auth, start here), certify_file, certify_with_confidence, verify_proof, get_proof, discover_services, audit_agent_session, check_attestations, investigate_proof. Resources: xproof://specification, xproof://openapi. Stateless (no session management). Protocol version: 2025-03-26.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"integer","example":1},"method":{"type":"string","enum":["initialize","tools/list","tools/call","resources/list","resources/read"],"example":"initialize"},"params":{"type":"object","description":"Method-specific parameters"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"integer"},"result":{"type":"object","description":"Method-specific result"}}}}}},"401":{"description":"Invalid or missing API key (for authenticated methods like tools/call)"}}}},"/api/proof":{"post":{"summary":"Certify a file (simplified)","description":"Single-call endpoint for AI agents. Creates a blockchain certification by recording the SHA-256 hash on MultiversX. No checkout flow needed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["file_hash","filename"],"properties":{"file_hash":{"type":"string","description":"SHA-256 hash of the file (64 hex chars)","example":"a1b2c3d4e5f678901234567890123456789012345678901234567890123456ab"},"filename":{"type":"string","example":"document.pdf"},"author_name":{"type":"string","example":"AI Agent","description":"Optional author name"},"webhook_url":{"type":"string","format":"uri","description":"Optional HTTPS URL to receive a POST notification when the proof is confirmed on-chain. Payload includes proof_id, file_hash, verify_url, blockchain details. Signed with X-xProof-Signature (HMAC-SHA256).","example":"https://your-agent.example.com/webhooks/xproof"}}}}}},"responses":{"200":{"description":"File already certified (returns existing proof)"},"201":{"description":"File certified successfully","content":{"application/json":{"schema":{"type":"object","properties":{"proof_id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"certified"},"file_hash":{"type":"string"},"filename":{"type":"string"},"verify_url":{"type":"string","format":"uri"},"certificate_url":{"type":"string","format":"uri"},"proof_json_url":{"type":"string","format":"uri"},"blockchain":{"type":"object","properties":{"network":{"type":"string","example":"MultiversX"},"transaction_hash":{"type":"string"},"explorer_url":{"type":"string","format":"uri"}}},"timestamp":{"type":"string","format":"date-time"},"webhook_status":{"type":"string","enum":["pending","delivered","failed","not_requested","not_applicable"],"description":"Webhook delivery status. 'pending': delivery in progress, 'delivered': successfully sent, 'failed': delivery failed after retries or invalid URL, 'not_requested': no webhook_url provided, 'not_applicable': file was already certified."},"message":{"type":"string"}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"API key required"},"429":{"description":"Rate limit exceeded"}}}},"/api/audit":{"post":{"summary":"Certify an agent audit log","description":"Agent Audit Log Standard — certify an AI agent's work session on the MultiversX blockchain BEFORE executing any critical action (trade, deploy, data access). Returns a proof_id that serves as a compliance certificate. The agent MUST call this endpoint before acting. Schema: /.well-known/agent-audit-schema.json","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id","session_id","action_type","action_description","inputs_hash","risk_level","decision","timestamp"],"properties":{"agent_id":{"type":"string","description":"Identifier of the agent making the decision","example":"trading-bot-v2"},"session_id":{"type":"string","description":"Unique session identifier (UUID)","example":"sess_20260227_001"},"action_type":{"type":"string","enum":["trade_execution","code_deploy","data_access","content_generation","api_call","other"]},"action_description":{"type":"string","description":"Human-readable description of the action","example":"Buy 0.5 ETH at market price on Uniswap v3"},"inputs_hash":{"type":"string","description":"SHA-256 of all inputs analyzed (64 hex chars)","example":"a1b2c3d4e5f678901234567890123456789012345678901234567890123456ab"},"inputs_manifest":{"type":"object","description":"Optional declaration of what inputs_hash covers (field names, sources, hash method) — enables regulatory audit without revealing values","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"Input field names included in the hash"},"sources":{"type":"array","items":{"type":"string"},"description":"Data sources consulted"},"hash_method":{"type":"string","description":"How the hash was computed"}},"required":["fields"]},"risk_level":{"type":"string","enum":["low","medium","high","critical"]},"decision":{"type":"string","enum":["approved","rejected","deferred"]},"timestamp":{"type":"string","format":"date-time","example":"2026-02-27T23:00:00Z"},"risk_summary":{"type":"string","description":"Optional brief risk analysis"},"context":{"type":"object","description":"Optional additional context"}}}}}},"responses":{"201":{"description":"Audit log certified on blockchain","content":{"application/json":{"schema":{"type":"object","properties":{"proof_id":{"type":"string","format":"uuid"},"audit_url":{"type":"string","format":"uri"},"proof_url":{"type":"string","format":"uri"},"blockchain":{"type":"object","properties":{"network":{"type":"string"},"transaction_hash":{"type":"string"},"explorer_url":{"type":"string","format":"uri"}}},"decision":{"type":"string"},"risk_level":{"type":"string"},"inputs_hash":{"type":"string"},"inputs_manifest":{"type":"object","description":"Present when submitted — declares what the inputs_hash covers"}}}}}},"400":{"description":"Invalid audit log data"},"401":{"description":"API key required"},"429":{"description":"Rate limit exceeded"}}}},"/api/agent/register":{"post":{"summary":"Register a free trial agent","description":"Get a free API key instantly — 10 blockchain certifications included. No wallet, no payment, no credit card required. This is the recommended first step for AI agents integrating with xproof.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name"],"properties":{"agent_name":{"type":"string","minLength":1,"maxLength":100,"description":"A unique name for your agent","example":"my-trading-bot"},"webhook_url":{"type":"string","format":"uri","description":"Optional HTTPS webhook URL to receive certification notifications","example":"https://your-agent.example.com/webhooks/xproof"}}}}}},"responses":{"201":{"description":"Trial registration successful — API key returned immediately","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"pm_ prefixed API key — use as Bearer token in Authorization header","example":"pm_abc123..."},"agent_name":{"type":"string"},"trial":{"type":"object","properties":{"quota":{"type":"integer","example":10},"remaining":{"type":"integer","example":10},"reset":{"type":"string","description":"Trial does not reset — quota is lifetime"}}},"certify_endpoint":{"type":"string","format":"uri","description":"Use this URL to certify files: POST /api/proof with Authorization: Bearer pm_YOUR_KEY"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid request (agent_name missing or malformed)"},"409":{"description":"Agent name already registered"},"429":{"description":"Too many registrations from this IP"}}}},"/api/agent/status":{"get":{"summary":"Check agent trial status","description":"Returns the remaining trial quota and usage statistics for the authenticated agent.","responses":{"200":{"description":"Agent status","content":{"application/json":{"schema":{"type":"object","properties":{"agent_name":{"type":"string"},"is_trial":{"type":"boolean"},"trial_quota":{"type":"integer","example":10},"trial_used":{"type":"integer","example":3},"trial_remaining":{"type":"integer","example":7},"credit_balance":{"type":"integer","description":"Prepaid credit balance (post-trial)"}}}}}},"401":{"description":"API key required"}}}},"/api/batch":{"post":{"summary":"Batch certify multiple files","description":"Certify up to 50 files in a single request. Each file is recorded individually on MultiversX blockchain. Consumes one credit per file. Returns an array of proof results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","maxItems":50,"description":"Array of files to certify","items":{"type":"object","required":["file_hash","filename"],"properties":{"file_hash":{"type":"string","description":"SHA-256 hash (64 hex chars)","example":"a1b2c3d4e5f678901234567890123456789012345678901234567890123456ab"},"filename":{"type":"string","example":"report.pdf"},"author_name":{"type":"string","example":"AI Agent"},"metadata":{"type":"object","description":"Optional key-value metadata (searchable)","additionalProperties":true}}}},"webhook_url":{"type":"string","format":"uri","description":"Optional HTTPS URL to receive notifications for each certified file"}}}}}},"responses":{"207":{"description":"Multi-status — array of results, one per file. Each result has its own status code.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"file_hash":{"type":"string"},"status":{"type":"string","enum":["certified","already_certified","error"]},"proof_id":{"type":"string","format":"uuid"},"verify_url":{"type":"string","format":"uri"},"blockchain":{"type":"object","properties":{"transaction_hash":{"type":"string"},"explorer_url":{"type":"string","format":"uri"}}}}}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"certified":{"type":"integer"},"already_certified":{"type":"integer"},"errors":{"type":"integer"}}}}}}}},"400":{"description":"Invalid request (too many files, missing fields)"},"401":{"description":"API key required"},"402":{"description":"Payment required — trial exhausted or no credits (x402 protocol response body includes payment instructions)"},"429":{"description":"Rate limit exceeded"}}}}}}