{"openapi":"3.1.0","info":{"title":"Axiv Pay Integration Hub API","version":"1.0.0","description":"Public discovery and operator integration records. Includes a simulation-only payment sandbox. No endpoint in this contract signs or submits a live payment."},"servers":[{"url":"https://pay.axiv.cc"}],"paths":{"/.well-known/axiv-pay.json":{"get":{"operationId":"getDiscoveryManifest","responses":{"200":{"description":"Public discovery manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/catalog":{"get":{"operationId":"listPublicCapabilities","parameters":[{"in":"query","name":"mode","schema":{"type":"string","enum":["live","demo"],"default":"live"},"description":"Operating registry or isolated demonstration fixture."},{"in":"query","name":"q","schema":{"type":"string"},"description":"Search across names, examples, workflow and quickstart."},{"in":"query","name":"role","schema":{"type":"string","enum":["user","merchant","agent"]}},{"in":"query","name":"chain","schema":{"type":"string"},"description":"CAIP-2 network ID."},{"in":"query","name":"asset","schema":{"type":"string"},"description":"Exact token symbol."},{"in":"query","name":"category","schema":{"type":"string","enum":["discovery","route","payment","tracking","protocol"]}},{"in":"query","name":"status","schema":{"type":"string","enum":["verified","partial","planned","blocked"]}}],"responses":{"200":{"description":"Public catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/capabilities/{id}":{"get":{"operationId":"getPublicCapability","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"mode","schema":{"type":"string","enum":["live","demo"],"default":"live"},"description":"Operating registry or isolated demonstration fixture."}],"responses":{"200":{"description":"Public capability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feature"}}}},"404":{"description":"Unknown or private capability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/example/{id}":{"get":{"operationId":"getExampleFixture","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Demonstration request and response","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"demo"},"id":{"type":"string"},"request":{"type":"object"},"response":{"type":"object"}},"required":["mode","id","request","response"]}}}},"404":{"description":"Unknown or private capability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workspace":{"get":{"operationId":"readWorkspace","parameters":[{"in":"query","name":"mode","schema":{"type":"string","enum":["live","demo"],"default":"live"},"description":"Operating registry or isolated demonstration fixture."}],"description":"Returns public view for anonymous visitors and full operating workspace for authorized operators.","responses":{"200":{"description":"Workspace state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}}}}},"/api/v1/registry":{"put":{"operationId":"replaceOperatingRegistry","security":[{"operatorBearer":[]},{"sitesSession":[]}],"description":"Replace operating registry after validating fields and the expected revision. A successful replacement increases the revision.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryInput"}}}},"responses":{"200":{"description":"New operating workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Operator authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Operator access or request origin rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision conflict or adapter configuration missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/checks/{id}":{"post":{"operationId":"runReadOnlyCheck","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"description":"Demo works with no credentials. Live checks require operator authorization and retain the response summary. Use a verification request ID to deduplicate writes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["live","demo"]},"requestId":{"type":"string","format":"uuid"}},"required":["mode"]}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Operator authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Operator access or request origin rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision conflict or adapter configuration missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mock/v1/capabilities":{"get":{"operationId":"getSandboxCapabilities","responses":{"200":{"description":"Simulated routes, fees, and supported states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCapabilities"}}}}}}},"/mock/v1/quotes":{"post":{"operationId":"createSandboxQuote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxQuoteInput"},"example":{"source":{"chainId":"8453","asset":"USDC","amountAtomic":"10000000"},"destination":{"chainId":"4663","asset":"USDG","recipient":"0x000000000000000000000000000000000000dEaD"},"fundingMode":"DIRECT"}}}},"responses":{"201":{"description":"Simulated quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxQuote"}}}},"400":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"422":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"429":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"503":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}}}}},"/mock/v1/payments":{"post":{"operationId":"createSandboxPayment","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Use a fresh UUID per payment intent and retain it during retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"},"merchantReference":{"type":"string"}},"required":["quoteId"]}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPayment"}}}},"201":{"description":"New simulated payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPayment"}}}},"400":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"404":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"409":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"410":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"503":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}}}}},"/mock/v1/payments/{id}":{"get":{"operationId":"getSandboxPayment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Sandbox payment ID returned by createSandboxPayment."}],"responses":{"200":{"description":"Simulated payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPayment"}}}},"404":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"503":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}}}}},"/mock/v1/payments/{id}/events":{"get":{"operationId":"getSandboxEvents","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Sandbox payment ID returned by createSandboxPayment."}],"responses":{"200":{"description":"Simulated events","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"paymentId":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/SandboxEvent"}}},"required":["mode","simulation","paymentId","events"]}}}},"404":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"503":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}}}}},"/mock/v1/payments/{id}/simulate":{"post":{"operationId":"advanceSandboxPayment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Sandbox payment ID returned by createSandboxPayment."}],"description":"Advance by one state. Resend the same expectedStatus to retry without advancing twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedStatus":{"type":"string","enum":["AWAITING_DEPOSIT","DEPOSIT_OBSERVED","GUARANTEED","PAYOUT_PENDING","PAID","SETTLED"]}},"required":["expectedStatus"]}}}},"responses":{"200":{"description":"Updated simulated payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPayment"}}}},"400":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"404":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"409":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"410":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}},"503":{"description":"Sandbox error","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"error":{"type":"string"}},"required":["mode","simulation","error"]}}}}}}},"/api/v1/report":{"get":{"operationId":"getReleaseReport","parameters":[{"in":"query","name":"mode","schema":{"type":"string","enum":["live","demo"],"default":"live"},"description":"Operating registry or isolated demonstration fixture."}],"responses":{"200":{"description":"Checklist, latest reads and release readiness","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"operatorBearer":{"type":"http","scheme":"bearer","description":"AXIV_INGEST_TOKEN configured as a Site secret."},"sitesSession":{"type":"apiKey","in":"cookie","name":"Sites authentication session","description":"Sign in via the Site and use an operator email registered in AXIV_OPERATOR_EMAILS."}},"schemas":{"SandboxQuoteInput":{"type":"object","properties":{"source":{"type":"object","properties":{"chainId":{"type":"string"},"asset":{"type":"string"},"amountAtomic":{"type":"string","pattern":"^[1-9][0-9]{0,12}$","description":"Decimal integer string in six-decimal atomic units."}},"required":["chainId","asset","amountAtomic"]},"destination":{"type":"object","properties":{"chainId":{"type":"string"},"asset":{"type":"string"},"recipient":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["chainId","asset","recipient"]},"fundingMode":{"type":"string","enum":["DIRECT","PREFUNDED"]}},"required":["source","destination","fundingMode"]},"SandboxQuote":{"allOf":[{"$ref":"#/components/schemas/SandboxQuoteInput"},{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"quoteId":{"type":"string"},"minReceiveAtomic":{"type":"string","pattern":"^[1-9][0-9]{0,12}$","description":"Decimal integer string in six-decimal atomic units."},"feeAtomic":{"type":"string","pattern":"^[1-9][0-9]{0,12}$","description":"Decimal integer string in six-decimal atomic units."},"feeBps":{"type":"integer","minimum":0},"expiresAt":{"type":"string","format":"date-time"}},"required":["mode","simulation","quoteId","minReceiveAtomic","feeAtomic","feeBps","expiresAt"]}]},"SandboxCapabilities":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"version":{"type":"string"},"fundingModes":{"type":"array","items":{"type":"string","enum":["DIRECT","PREFUNDED"]}},"amountDecimals":{"type":"integer","minimum":0},"feeBps":{"type":"integer","minimum":0},"routes":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","properties":{"chainId":{"type":"string"},"asset":{"type":"string"}},"required":["chainId","asset"]},"destination":{"type":"object","properties":{"chainId":{"type":"string"},"asset":{"type":"string"}},"required":["chainId","asset"]}},"required":["source","destination"]}},"paymentStates":{"type":"array","items":{"type":"string","enum":["AWAITING_DEPOSIT","DEPOSIT_OBSERVED","GUARANTEED","PAYOUT_PENDING","PAID","SETTLED"]}},"guarantees":{"const":"SIMULATED"}},"required":["mode","simulation","version","fundingModes","amountDecimals","feeBps","routes","paymentStates","guarantees"]},"SandboxPayment":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"paymentId":{"type":"string"},"quoteId":{"type":"string"},"merchantReference":{"type":"string"},"status":{"type":"string","enum":["AWAITING_DEPOSIT","DEPOSIT_OBSERVED","GUARANTEED","PAYOUT_PENDING","PAID","SETTLED"]},"guarantee":{"type":["object","null"]},"payout":{"type":["object","null"]},"settlement":{"type":["object","null"]}},"required":["mode","simulation","paymentId","quoteId","merchantReference","status","guarantee","payout","settlement"]},"SandboxEvent":{"type":"object","properties":{"mode":{"const":"mock"},"simulation":{"const":true},"sequence":{"type":"integer","minimum":0},"status":{"type":"string","enum":["AWAITING_DEPOSIT","DEPOSIT_OBSERVED","GUARANTEED","PAYOUT_PENDING","PAID","SETTLED"]},"at":{"type":"string","format":"date-time"}},"required":["mode","simulation","sequence","status","at"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Chain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"assets":{"type":"array","items":{"type":"string"}},"proof":{"type":"string"}},"required":["id","name","assets","proof"]},"Feature":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"en":{"type":"string"},"category":{"type":"string","enum":["discovery","route","payment","tracking","protocol"]},"description":{"type":"string"},"roles":{"type":"array","items":{"type":"string","enum":["user","merchant","agent"]}},"chains":{"type":"array","items":{"type":"string"}},"assets":{"type":"array","items":{"type":"string"}},"endpoint":{"type":"string"},"path":{"type":"string"},"adapter":{"type":"string"},"status":{"type":"string","enum":["verified","partial","planned","blocked"]},"version":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"verifiedAt":{"type":"string","description":"YYYY-MM-DD, or empty when unverified. Required for verified status."},"docs":{"type":"string"},"flow":{"type":"array","items":{"type":"string"}},"request":{"type":"object"},"response":{"type":"object"},"command":{"type":"string"},"gap":{"type":"string"}},"required":["id","title","category","description","roles","chains","assets","endpoint","status","version","visibility","verifiedAt","flow","request","response","command"]},"Adapter":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"monogram":{"type":"string"},"layer":{"type":"string"},"description":{"type":"string"},"surfaces":{"type":"array","items":{"type":"string","enum":["request","quote","settlement"]}},"connect":{"type":"string"},"url":{"type":"string"},"request":{"type":"string"},"status":{"type":"string","enum":["verified","partial","planned","blocked"]},"version":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"verifiedAt":{"type":"string","description":"YYYY-MM-DD, or empty when unverified. Required for verified status."},"gap":{"type":"string"}},"required":["id","title","layer","description","surfaces","connect","request","status","visibility","verifiedAt"]},"Resource":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["Docs","GitHub","OpenAPI","SDK","MCP","Agent Skill","API"]},"url":{"type":"string"},"status":{"type":"string","enum":["verified","partial","planned","blocked"]},"version":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"verifiedAt":{"type":"string","description":"YYYY-MM-DD, or empty when unverified. Required for verified status."},"note":{"type":"string"}},"required":["id","title","type","url","status","version","visibility","verifiedAt"]},"Registry":{"type":"object","properties":{"chains":{"type":"array","items":{"$ref":"#/components/schemas/Chain"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/Feature"}},"adapters":{"type":"array","items":{"$ref":"#/components/schemas/Adapter"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}},"assignments":{"type":"object","properties":{"request":{"type":"string"},"quote":{"type":"string"},"settlement":{"type":"string"}},"required":["request","quote","settlement"]},"checklist":{"type":"object","properties":{"user":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"note":{"type":"string"},"state":{"type":"string","enum":["todo","doing","done"]}},"required":["id","title","note","state"]}},"merchant":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"note":{"type":"string"},"state":{"type":"string","enum":["todo","doing","done"]}},"required":["id","title","note","state"]}},"agent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"note":{"type":"string"},"state":{"type":"string","enum":["todo","doing","done"]}},"required":["id","title","note","state"]}}},"required":["user","merchant","agent"]},"gaps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"note":{"type":"string"},"state":{"type":"string","enum":["todo","doing","done"]},"required":{"type":"boolean"}},"required":["id","title","note","state","required"]}}},"required":["chains","features","adapters","resources","assignments","checklist","gaps"]},"Catalog":{"type":"object","properties":{"schemaVersion":{"const":1},"version":{"type":"string"},"mode":{"type":"string","enum":["live","demo"]},"features":{"type":"array","items":{"$ref":"#/components/schemas/Feature"}},"adapters":{"type":"array","items":{"$ref":"#/components/schemas/Adapter"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}},"chains":{"type":"array","items":{"$ref":"#/components/schemas/Chain"}},"links":{"type":"object"},"note":{"type":"string"}},"required":["schemaVersion","version","mode","features","adapters","resources","chains","links","note"]},"RegistryInput":{"type":"object","properties":{"schemaVersion":{"const":1},"mode":{"const":"live"},"expectedRevision":{"type":"integer","minimum":0},"registry":{"$ref":"#/components/schemas/Registry"}},"required":["schemaVersion","mode","expectedRevision","registry"]},"Workspace":{"type":"object","properties":{"schemaVersion":{"const":1},"mode":{"type":"string","enum":["live","demo"]},"revision":{"type":["integer","null"]},"registry":{"$ref":"#/components/schemas/Registry"},"runs":{"type":"array","items":{"$ref":"#/components/schemas/Run"}},"permissions":{"type":"object","properties":{"canWrite":{"type":"boolean"},"signedIn":{"type":"boolean"}},"required":["canWrite","signedIn"]},"probes":{"type":"array","items":{"type":"object"}},"report":{"type":"object"}},"required":["schemaVersion","mode","revision","registry","runs","permissions","probes","report"]},"Run":{"type":"object","properties":{"id":{"type":"string"},"checkId":{"type":"string"},"label":{"type":"string"},"target":{"type":"string"},"at":{"type":"string"},"mode":{"type":"string","enum":["live","demo"]},"source":{"type":"string"},"result":{"type":"string","enum":["pass","fail"]},"httpStatus":{"type":["integer","null"]},"latencyMs":{"type":"integer","minimum":0},"summary":{"type":"string"},"evidence":{"type":"object"}},"required":["id","checkId","label","target","at","mode","source","result","httpStatus","latencyMs","summary","evidence"]}}}}