{
  "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_\u2026 or vw_test_\u2026"
      }
    },
    "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"
                      }
                    }
                  },
                  "claims": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "over_18",
                        "over_21",
                        "country",
                        "nationality",
                        "not_sanctioned"
                      ]
                    }
                  },
                  "proof_of_funds": {
                    "oneOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "min_usd": {
                            "type": "number"
                          }
                        }
                      }
                    ]
                  },
                  "test_outcome": {
                    "type": "object",
                    "properties": {
                      "identity": {
                        "type": "string",
                        "enum": [
                          "verified",
                          "rejected",
                          "pending"
                        ]
                      },
                      "aml": {
                        "type": "string",
                        "enum": [
                          "clear",
                          "review",
                          "flagged",
                          "pending"
                        ]
                      },
                      "business": {
                        "type": "string",
                        "enum": [
                          "verified",
                          "rejected",
                          "pending"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "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"
          }
        }
      }
    },
    "/api/v1/screen": {
      "post": {
        "summary": "Screen any address (AML)",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "properties": {
                  "address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Signed screening result"
          },
          "400": {
            "description": "Invalid address"
          },
          "402": {
            "description": "Account paused or over its limit"
          }
        }
      }
    },
    "/api/v1/verifications/{id}/evidence": {
      "get": {
        "summary": "Evidence pack for one verification",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "html"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Evidence pack (JSON, or printable HTML)"
          }
        }
      }
    },
    "/api/check/{address}": {
      "get": {
        "summary": "Check before you send (free, no key)",
        "security": [],
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "verdict (warning | risk | business | verified | revoked | unknown), summary, certificates, directory, lookalikes"
          }
        }
      }
    },
    "/api/directory": {
      "get": {
        "summary": "Business directory (free, no key)",
        "security": [],
        "responses": {
          "200": {
            "description": "Listed company wallets"
          }
        }
      }
    }
  }
}