{
  "openapi": "3.1.0",
  "info": { "title": "VerifiedWallet API", "version": "1", "description": "Wallet ownership verification with optional identity, AML and company checks. Docs: https://verifiedwallet.io/developers" },
  "servers": [{ "url": "https://verifiedwallet.io" }],
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "vw_live_… or vw_test_…" } },
    "schemas": {
      "Verification": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "ver_3f9a1c0b7e44d2a9f61c" },
          "object": { "const": "verification" },
          "mode": { "enum": ["live", "test"] },
          "tier": { "enum": [1, 2, 3, 4] },
          "status": { "enum": ["pending", "completed", "expired"] },
          "reference": { "type": ["string", "null"] },
          "metadata": { "type": "object", "additionalProperties": { "type": "string" } },
          "business": { "type": ["object", "null"] },
          "monitor": { "type": "boolean" },
          "returnUrl": { "type": ["string", "null"] },
          "certificateId": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "completedAt": { "type": ["string", "null"], "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "description": "Only on create: the link for the customer." },
          "certificate": { "$ref": "#/components/schemas/CertificateResult" }
        }
      },
      "CertificateResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string" },
          "chain": { "type": "string" },
          "wallet": { "type": "string" },
          "tier": { "type": "integer" },
          "issuedAt": { "type": "string", "format": "date-time" },
          "account": { "type": ["object", "null"], "description": "Smart-contract or multisig details" },
          "identity": { "type": ["object", "null"], "properties": { "status": { "enum": ["pending", "verified", "rejected"] }, "provider": { "type": "string" } } },
          "aml": { "type": ["object", "null"], "properties": { "status": { "enum": ["pending", "clear", "review", "flagged"] } } },
          "business": { "type": ["object", "null"] },
          "revoked": { "type": "boolean" },
          "test": { "type": "boolean" },
          "core": { "type": "object", "description": "The signed certificate data" },
          "attestation": { "type": "object", "properties": { "alg": { "const": "ES256" }, "kid": { "type": "string" }, "sig": { "type": "string" } } }
        }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } }
    }
  },
  "paths": {
    "/api/v1/verifications": {
      "post": {
        "summary": "Create a verification",
        "security": [{ "apiKey": [] }],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {
          "tier": { "enum": [1, 2, 3, 4] }, "reference": { "type": "string" }, "wallet": { "type": "string" }, "chain": { "type": "string" },
          "return_url": { "type": "string" }, "monitor": { "type": "boolean" }, "metadata": { "type": "object" },
          "business": { "type": "object", "properties": { "company_name": { "type": "string" }, "country": { "type": "string" }, "registration_number": { "type": "string" } } } } } } } },
        "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bad key" } }
      },
      "get": { "summary": "List verifications", "security": [{ "apiKey": [] }], "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } }], "responses": { "200": { "description": "OK" } } }
    },
    "/api/v1/verifications/{id}": { "get": { "summary": "Retrieve a verification", "security": [{ "apiKey": [] }], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "404": { "description": "Not found" } } } },
    "/api/v1/usage": { "get": { "summary": "Usage for a month", "security": [{ "apiKey": [] }], "parameters": [{ "name": "month", "in": "query", "schema": { "type": "string", "example": "2026-10" } }], "responses": { "200": { "description": "OK" } } } },
    "/api/verify/{query}": { "get": { "summary": "Public register lookup (free)", "parameters": [{ "name": "query", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } },
    "/api/cert/{id}": { "get": { "summary": "A certificate (free)", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } },
    "/api/attester": { "get": { "summary": "Our public signing key (free)", "responses": { "200": { "description": "OK" } } } }
  }
}