{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aspern-org/json-schema/aspern-org-agent-profile-schema.json",
  "title": "AgentProfile",
  "description": "Agent economic profile: four readings of one economic subject, with no score on top.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aspern-org-openapi.json#/components/schemas/AgentProfile",
  "type": "object",
  "required": [
    "data",
    "meta",
    "warnings"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "address",
        "format",
        "asOf",
        "revenue",
        "delivery",
        "dependencies",
        "health",
        "blocksAnswered",
        "cannotSee",
        "says"
      ],
      "description": "Four readings of one economic subject. There is no score on top of them, on purpose: a composite would be the figure every reader quotes and none can check. A block we have not computed is null rather than a row of zeros, which is why every one of the four is nullable.",
      "properties": {
        "address": {
          "type": "string",
          "description": "EVM lower-cased; any other kind as given."
        },
        "evidence": {
          "type": "object",
          "additionalProperties": true,
          "description": "The common payment record (TODO-07): `state` is `built` where one payment is described, with `facilitator` (who submitted the transfer, never credited with it), `onChainRecipient` (where the tokens went), `listedPayee` (the seller’s catalogue payTo), `facilitatorIsRecipient` and `recipientIsListedPayee` (false is a finding, null means a side is unread), `settlement`, `delivery`, `deliveryEvidence` and `says`; or `not-applicable`, with `says` naming why no single payment is described here."
        },
        "format": {
          "type": "object",
          "required": [
            "kind",
            "coverage",
            "says"
          ],
          "properties": {
            "kind": {
              "enum": [
                "evm",
                "cardano",
                "cardano-stake",
                "cardano-byron",
                "solana",
                "bitcoin",
                "cosmos",
                "unknown"
              ]
            },
            "chain": {
              "type": [
                "string",
                "null"
              ]
            },
            "network": {
              "enum": [
                "mainnet",
                "testnet",
                null
              ]
            },
            "coverage": {
              "enum": [
                "rails",
                "identity-only"
              ]
            },
            "says": {
              "type": "string"
            }
          }
        },
        "wellKnown": {
          "type": [
            "object",
            "null"
          ],
          "description": "Set where the address is not a party at all — a burn address, a router — so the four blocks below are not read as a business.",
          "properties": {
            "kind": {
              "type": "string"
            },
            "says": {
              "type": "string"
            }
          }
        },
        "asOf": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "revenue": {
          "type": [
            "object",
            "null"
          ],
          "description": "Income, repeat buyers, concentration, and whether its payers look like separate parties. Null where we hold no record of it trading.",
          "properties": {
            "dealings": {
              "type": "integer"
            },
            "buyers": {
              "type": "integer"
            },
            "usd": {
              "type": [
                "number",
                "null"
              ],
              "description": "Null, never 0, where no rail priced it.",
              "x-unit": "usd"
            },
            "repeatBuyers": {
              "type": "integer"
            },
            "repeatShare": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1.",
              "x-unit": "decimal-fraction"
            },
            "largestBuyerShare": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1. Null below three buyers, where a share could only be a half or a whole.",
              "x-unit": "decimal-fraction"
            },
            "independentBuyers": {
              "type": "integer"
            },
            "twoWayBuyers": {
              "type": "integer"
            },
            "recent": {
              "type": "object",
              "properties": {
                "dealings30": {
                  "type": "integer"
                },
                "dealings90": {
                  "type": "integer"
                },
                "newBuyers90": {
                  "type": "integer"
                }
              }
            },
            "from": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "to": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "sharedPayers": {
              "type": [
                "object",
                "null"
              ],
              "description": "Payers of this address that share an obscure third party with another of its payers. Evidence of a link, never proof of one operator.",
              "properties": {
                "payers": {
                  "type": "integer",
                  "x-unit": "count"
                },
                "linked": {
                  "type": "integer"
                },
                "viaParties": {
                  "type": "integer"
                },
                "largestGroup": {
                  "type": "integer"
                }
              }
            },
            "says": {
              "type": "string"
            }
          }
        },
        "delivery": {
          "type": [
            "object",
            "null"
          ],
          "description": "What a completion is worth. ACP v2 emits no accepted and no disputed phase, so neither is reported: `protocolCannotSay` names them rather than inventing them. `judged` is null until the nightly pass has computed it, which is not the same statement as nobody having judged anything.",
          "properties": {
            "jobs": {
              "type": "integer",
              "x-unit": "count"
            },
            "from": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "to": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "completed": {
              "type": "integer"
            },
            "rejected": {
              "type": "integer"
            },
            "expired": {
              "type": "integer"
            },
            "reachedAnOutcome": {
              "type": "integer",
              "description": "completed + rejected + expired: the denominator of completionOfEnded."
            },
            "inFlight": {
              "type": [
                "integer",
                "null"
              ]
            },
            "phaseUnread": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Jobs we hold with no phase event decoded. Our silence, not a state the chain reported."
            },
            "refunded": {
              "type": [
                "integer",
                "null"
              ]
            },
            "completionOfEnded": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1, over jobs that ENDED. Read it with the two figures below or it reads as a record of all the work."
            },
            "outcomeCoverage": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1: jobs that reached an outcome over ALL jobs. What completionOfEnded covers. Null where there are no jobs."
            },
            "phaseUnreadShare": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1: jobs with no phase we could decode, over all jobs. OURS rather than the chain’s, and why outcomeCoverage is not larger.",
              "x-unit": "decimal-fraction"
            },
            "judged": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "thirdParty": {
                  "type": "integer"
                },
                "buyer": {
                  "type": "integer"
                },
                "self": {
                  "type": "integer"
                },
                "nobody": {
                  "type": "integer"
                },
                "of": {
                  "type": "integer"
                }
              }
            },
            "thirdPartyShare": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1.",
              "x-unit": "decimal-fraction"
            },
            "protocolCannotSay": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "says": {
              "type": "string"
            }
          }
        },
        "dependencies": {
          "type": [
            "object",
            "null"
          ],
          "description": "Who it pays, split by the EVIDENCE that they supply it rather than by how sure we feel. Null where its recipients have not been split yet.",
          "properties": {
            "parties": {
              "type": "integer"
            },
            "contracted": {
              "$ref": "#/$defs/SupplierClass"
            },
            "listed": {
              "$ref": "#/$defs/SupplierClass"
            },
            "paidOnly": {
              "$ref": "#/$defs/SupplierClass"
            },
            "paidBack": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Recipients that have also paid this address. Cuts across the three."
            },
            "contractedShareOfSpend": {
              "type": [
                "number",
                "null"
              ],
              "description": "0..1.",
              "x-unit": "decimal-fraction"
            },
            "says": {
              "type": "string"
            }
          }
        },
        "health": {
          "type": "object",
          "description": "Whether its listed endpoints answer, and how recently it traded. The unpaid half of the handshake: an endpoint that quotes may still fail to deliver once paid.",
          "properties": {
            "endpointsListed": {
              "type": "integer"
            },
            "endpointsProbed": {
              "type": "integer",
              "description": "Of the listed ones. The rest are unknocked, not broken."
            },
            "quoting": {
              "type": "integer"
            },
            "gone": {
              "type": "integer"
            },
            "unreachable": {
              "type": "integer"
            },
            "otherAnswer": {
              "type": "integer"
            },
            "lastProbedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "lastDealingAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "quietForDays": {
              "type": [
                "integer",
                "null"
              ],
              "x-unit": "days"
            },
            "says": {
              "type": "string"
            }
          }
        },
        "blocksAnswered": {
          "type": "integer",
          "description": "How many of the four blocks above this answer could fill, 0 to 4. Read it as the denominator of everything above: three readings out of four is a different statement from four, and a reader who cannot see which has no way to weigh the profile against another agent’s. The answer has always carried it; it was missing from THIS document for a day, so a paying reader of the contract was not told about the one field that qualifies all the others."
        },
        "cannotSee": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What no block above can reach. Carried with the profile rather than buried in one of them."
        },
        "says": {
          "type": "string"
        }
      }
    },
    "meta": {
      "$ref": "#/$defs/Meta"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Warning"
      }
    }
  },
  "$defs": {
    "Meta": {
      "type": "object",
      "required": [
        "requestId",
        "snapshotId",
        "servedAt",
        "methodologyVersion",
        "coverage"
      ],
      "properties": {
        "requestId": {
          "type": "string",
          "description": "Also the X-Request-Id header."
        },
        "environment": {
          "type": "string",
          "description": "production, staging or development. Also the X-ASPERN-Environment header and info.x-aspern-environment in the OpenAPI document, so a client can tell which contract answered."
        },
        "build": {
          "type": [
            "string",
            "null"
          ],
          "description": "The deploy that served this. Also the X-ASPERN-Build header."
        },
        "snapshotId": {
          "type": "string",
          "description": "Which state of our data answered. Two responses with the same snapshotId saw the same completed ingest runs — so a figure that differs between two surfaces under the SAME snapshot is a defect, and under different ones is a clock."
        },
        "observedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the source was observed."
        },
        "computedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When we computed this from it."
        },
        "servedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When this response was built."
        },
        "methodologyVersion": {
          "type": "string",
          "description": "What the figures mean. Changes are listed at /changelog."
        },
        "source": {
          "type": [
            "string",
            "null"
          ]
        },
        "chainId": {
          "type": [
            "integer",
            "null"
          ],
          "x-unit": "chain-id"
        },
        "blockNumber": {
          "type": [
            "integer",
            "null"
          ],
          "x-unit": "block-number"
        },
        "coverage": {
          "type": "object",
          "properties": {
            "scope": {
              "type": [
                "string",
                "null"
              ],
              "description": "What this covers and, explicitly, what it does not."
            },
            "population": {
              "type": [
                "string",
                "null"
              ],
              "description": "The population these figures were measured over, as a key you can join on rather than a sentence you have to read. Every key is declared once and resolves to a definition at /reconciliation#<key>, where the ones that narrow show every row that falls out and why. The same key appears beside the figure on the website, so an integrator and a reader are talking about one population rather than two descriptions of it. Null only when `populationAbsence` says why."
            },
            "populationAbsence": {
              "type": [
                "string",
                "null"
              ],
              "description": "Why there is no single population, where there is none. A lookup of one address measures nothing; a document carrying several rails in units that are never summed carries several populations. A null population with nothing here would be an absence you could not tell from an oversight, which is the defect this field exists to close."
            },
            "knownExclusions": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              },
              "description": "THREE VALUES. A list is what this route deliberately leaves out. `[]` is a CLAIM that nothing is excluded. `null` is “we have not said”, which is our gap and must never be read as the second. It was hardcoded to `[]` on every route until 2026-09-27, so every response claimed to exclude nothing while its own `scope` sentence named exclusions."
            }
          }
        },
        "confidence": {
          "type": [
            "object",
            "null"
          ],
          "description": "Never a bare number; it names what it is a confidence in."
        },
        "freshness": {
          "anyOf": [
            {
              "type": "object",
              "required": [
                "oldestObservedAt",
                "newestObservedAt",
                "readings",
                "fields",
                "complete",
                "state",
                "newestAgeHours"
              ],
              "description": "When the readings behind this answer were taken, where they differ. A page of a hundred vaults read over four hours has no single observation time — `observedAt` is filled in only where every reading agrees, and this reports the spread otherwise.",
              "properties": {
                "oldestObservedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "newestObservedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "readings": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "How many readings the range was taken over.",
                  "x-unit": "count"
                },
                "fields": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The fields it was read from, so a caller can go and check any of them directly."
                },
                "complete": {
                  "type": "boolean",
                  "description": "Whether every reading in the payload was seen. False means the range is a LOWER BOUND — the true spread is at least this wide and may be wider — because a partial walk always returns the narrower range, which would read as fresher and more uniform than the data is."
                },
                "state": {
                  "enum": [
                    "fresh",
                    "mixed",
                    "stale"
                  ],
                  "description": "`stale` when the NEWEST reading is more than 26 hours old at the moment the response was built — every reader runs at least daily, so that means a reader has stopped. `mixed` when the newest is inside that window and the OLDEST is not: parts of this answer are current and parts are not, which is the usual shape of a document joining several sources. It was summarised as `fresh` until 2026-10-10, computed from the newest reading alone, so one current field hid a catalogue two months old. A source that could not be read is not a state here: it is a check that could not run (`/v1/checks`) or an analysis whose `availability` says so, and never a zero."
                },
                "newestAgeHours": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Hours between the newest reading and the moment this response was built, to one decimal.",
                  "x-unit": "hours"
                },
                "oldestAgeHours": {
                  "type": "number",
                  "minimum": 0,
                  "description": "The same for the OLDEST reading. The other end of the spread as a number, because a caller comparing two ISO strings to find out whether part of an answer is two months old will mostly not bother.",
                  "x-unit": "hours"
                }
              }
            },
            {
              "type": "object",
              "required": [
                "reason",
                "state",
                "says",
                "readings"
              ],
              "description": "No range, and which of the two reasons it is.",
              "properties": {
                "reason": {
                  "enum": [
                    "not-applicable",
                    "no-dated-field"
                  ],
                  "description": "`not-applicable` is reference material: a plan, a capability list, a schema. Nothing in it was read from anywhere at a time. `no-dated-field` means the response carries data and nothing in it names when that data was read, which is a gap in that endpoint."
                },
                "state": {
                  "enum": [
                    "not_applicable",
                    "not_measured"
                  ],
                  "description": "The reason in the vocabulary shared with `fresh`/`stale`: `not-applicable` is `not_applicable`, `no-dated-field` is `not_measured`."
                },
                "says": {
                  "type": "string",
                  "description": "The same thing in a sentence."
                },
                "readings": {
                  "const": 0
                }
              }
            }
          ]
        },
        "pagination": {
          "anyOf": [
            {
              "$ref": "#/$defs/Page"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "Page": {
      "type": "object",
      "required": [
        "total",
        "limit",
        "offset",
        "hasMore"
      ],
      "properties": {
        "total": {
          "type": "integer",
          "minimum": 0,
          "description": "Rows matching the filter, not rows returned.",
          "x-unit": "count"
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "description": "Applied page size. May be below what was asked — X-Page-Limit says so when it is.",
          "x-unit": "count"
        },
        "offset": {
          "type": "integer",
          "minimum": 0,
          "x-unit": "count"
        },
        "hasMore": {
          "type": "boolean"
        },
        "nextOffset": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Null on the last page.",
          "x-unit": "count"
        },
        "orderedBy": {
          "type": "string",
          "description": "The sort, including its tie-breaker. The order is total, so paging cannot show a row twice or skip one."
        }
      }
    },
    "SupplierClass": {
      "type": "object",
      "required": [
        "parties",
        "usd",
        "evidence",
        "alsoCalled"
      ],
      "properties": {
        "parties": {
          "type": "integer"
        },
        "usd": {
          "type": [
            "number",
            "null"
          ],
          "description": "Null, never 0, where no rail priced the payments.",
          "x-unit": "usd"
        },
        "evidence": {
          "type": "string",
          "description": "The rule that put them here, in one sentence a reader can check."
        },
        "alsoCalled": {
          "type": "string",
          "description": "The same class in the vocabulary an auditor used: confirmedSupplier, likelySupplier, paymentRecipient."
        }
      }
    },
    "Warning": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}