custody.json

A custody provider publishes one file at https://<its domain>/.well-known/custody.json stating, in its own words, how it holds client bitcoin: the custody model, which institutions can sign and how many must, whether the client ever handles a key, how assets are segregated, which attestations exist and where, what the insurance limit is and on what basis, how withdrawals are controlled, and which incidents it has disclosed.

The point is not that the provider's statement is the truth. The point is that it is the provider's statement, dated, at the provider's domain, in a shape an agent can read and compare with regulator records, filings and the failure registry. Today those facts are scattered across marketing pages, PDFs and support articles, and assistants fill the gaps with whatever they retrieved. A disclosure file replaces the guess with the claim, and the claim can be checked.

Proof of Custody publishes the schema, validates files it finds and will index them alongside its own scores, with the provider's statement and the independent assessment shown side by side. It does not write a provider's file. Onramp Bitcoin, which publishes this site, will publish its own file first.

Schema

JSON Schema 2020-12: /schemas/custody.schema.json. Required fields: version, provider, asOf, custodyModel, keyholders, contact. Keyholders are institutions, not keys. The custody model uses the definitions in custody-models.json. Insurance states the limit exactly as the policy does, including whether it is aggregate or per client, because the difference is the fact most often misreported.

Example

{
  "version": "0.1",
  "asOf": "2026-10-19",
  "provider": {
    "name": "Example Custody",
    "legalName": "Example Custody Trust Company, LLC",
    "domain": "example.com",
    "jurisdiction": "US-SD",
    "registrations": [
      { "regulator": "South Dakota Division of Banking", "type": "trust company charter",
        "url": "https://dlr.sd.gov/banking/trust_companies/default.aspx" }
    ]
  },
  "custodyModel": "multi-institution-custody",
  "quorum": { "required": 2, "total": 3 },
  "keyholders": [
    { "name": "Example Custody", "role": "operator" },
    { "name": "Second Trust Co.", "role": "independent keyholder", "jurisdiction": "US-SD" },
    { "name": "Third Keyholder Ltd.", "role": "independent keyholder", "jurisdiction": "GB" }
  ],
  "holderHoldsKey": false,
  "segregation": "segregated-per-client",
  "attestations": [
    { "type": "SOC 2 Type II", "provider": "Audit Firm LLP", "date": "2026-06-30", "cadence": "annual",
      "url": "https://example.com/trust/soc2" }
  ],
  "insurance": { "carrier": "Syndicate at Lloyd's", "limit": "USD 50,000,000 aggregate", "basis": "aggregate",
    "whoPays": "provider", "url": "https://example.com/insurance" },
  "withdrawal": { "controls": "video verification, 24-hour delay", "typicalTime": "1 to 2 business days",
    "url": "https://example.com/help/withdrawals" },
  "incidents": [],
  "feed": "https://example.com/status.json",
  "contact": { "security": "security@example.com" }
}

What happens with a published file

• Proof of Custody fetches it daily, validates it against the schema and records the as-of date.
• The provider's record on this site shows the provider's statement next to the published score, labelled as the provider's own words.
• Where the statement and a third-party record disagree (a registration that does not appear in the regulator's list, an insurance basis stated differently in the policy), both are shown and the difference is noted.
• The MCP tools return the provider's statement with its URL, so an agent cites the provider for the provider's claims.

Status and feedback

Draft 0.1, 19 October 2026. Field names and enums may change before 1.0; files that validate against 0.1 will be read by 1.0. Comment on the dataset repository. Providers who publish a file can tell us there, or we will find it at the well-known path.