Portfolio

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/getchord-xyz/json-schema/getchord-xyz-portfolio-schema.json",
  "title": "Portfolio",
  "description": "One wallet on every chain in scope.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/getchord-xyz-portfolio-api-openapi.yml#/components/schemas/Portfolio",
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "EVM address, lower-case."
    },
    "sol": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
      "description": "The Solana address as given, or null."
    },
    "asOf": {
      "type": "integer",
      "description": "Unix time, milliseconds. When this answer was computed. A cached answer keeps its own `asOf`."
    },
    "totals": {
      "type": "object",
      "properties": {
        "valueUsd": {
          "type": "number",
          "description": "Sum of `valueUsd` over the chains that were read."
        },
        "cashUsd": {
          "type": "number",
          "description": ""
        },
        "pnl": {
          "type": "object",
          "properties": {
            "24h": {
              "$ref": "#/$defs/PortfolioWindow"
            },
            "7d": {
              "$ref": "#/$defs/PortfolioWindow"
            },
            "30d": {
              "$ref": "#/$defs/PortfolioWindow"
            }
          },
          "description": "Complete only when every chain in the answer is complete for that window, chains that could not be read included. `pct` is the sum of the chains' USD over the sum of their bases.",
          "required": [
            "24h",
            "7d",
            "30d"
          ]
        }
      }
    },
    "chains": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PortfolioChain"
      },
      "description": "In registry order, Solana last."
    }
  },
  "$defs": {
    "PortfolioChain": {
      "type": "object",
      "properties": {
        "chain": {
          "type": [
            "integer",
            "string"
          ],
          "description": "EVM chain id, or `solana`."
        },
        "key": {
          "type": "string",
          "description": "Registry key (`monad`, `base`, …) or `solana`."
        },
        "name": {
          "type": "string",
          "description": ""
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "partial",
            "unavailable"
          ],
          "description": "`ok` = read. `partial` = balances read, part of the rest (prices, the tape, some tokens) not, and `reason` says which. `unavailable` = not read at all: in no total, every window without a number."
        },
        "reason": {
          "type": "string",
          "description": "Present unless `ok`. One plain sentence for a person."
        },
        "valueUsd": {
          "type": "number",
          "description": "Sum of the priced holdings, small balances included."
        },
        "cashUsd": {
          "type": "number",
          "description": "The part of `valueUsd` held in stablecoins."
        },
        "pnl": {
          "type": "object",
          "properties": {
            "24h": {
              "$ref": "#/$defs/PortfolioWindow"
            },
            "7d": {
              "$ref": "#/$defs/PortfolioWindow"
            },
            "30d": {
              "$ref": "#/$defs/PortfolioWindow"
            }
          },
          "description": "The chain's PnL per window.",
          "required": [
            "24h",
            "7d",
            "30d"
          ]
        },
        "coverage": {
          "type": "object",
          "properties": {
            "tapeFromTs": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Unix time, milliseconds. First moment the chain's swap tape covers without a hole for this wallet. Null = no tape here."
            },
            "source": {
              "type": "string",
              "enum": [
                "tape",
                "tape+lake",
                "box"
              ],
              "description": "`tape` = Chord's raw tape of the chain; `tape+lake` = older days joined from Chord's history lake; `box` = Chord's Solana index."
            },
            "ingestFloorUsd": {
              "type": [
                "number",
                "null"
              ],
              "description": "Present on a chain whose tape does not record swaps under this many USD (BNB Chain: 100). Disclosed, not a hole: that chain's windows still count as complete, and a swap under the floor reads only as a price move or a transfer. Say so next to the numbers."
            }
          }
        },
        "holdings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PortfolioHolding"
          },
          "description": "Priced holdings worth at least $0.01, largest first, then the unpriced ones."
        },
        "dust": {
          "type": "object",
          "properties": {
            "count": {
              "type": "integer",
              "description": ""
            },
            "valueUsd": {
              "type": "number",
              "description": ""
            }
          },
          "description": "Priced holdings under $0.01, counted here and not listed."
        },
        "unpriced": {
          "type": "integer",
          "description": "Holdings with `priceUsd: null` (listed at the end of `holdings`)."
        }
      },
      "description": "One chain of a portfolio."
    },
    "PortfolioHolding": {
      "type": "object",
      "properties": {
        "address": {
          "type": [
            "string",
            "null"
          ],
          "description": "EVM token, lower-case. Null for the chain's native coin and on a Solana row (which carries `mint`)."
        },
        "mint": {
          "type": "string",
          "description": "Solana rows only: the mint, case kept."
        },
        "symbol": {
          "type": "string",
          "description": ""
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": ""
        },
        "decimals": {
          "type": "integer",
          "description": "From the chain's list or the chain itself, never assumed."
        },
        "logo": {
          "type": [
            "string",
            "null"
          ],
          "description": ""
        },
        "native": {
          "type": "boolean",
          "description": "The chain's own coin (ETH, MON, AVAX, BNB, USDC on Arc, SOL)."
        },
        "stable": {
          "type": "boolean",
          "description": "A dollar stablecoin: counted in `cashUsd`, left out of PnL."
        },
        "amount": {
          "type": "string",
          "description": "Balance in whole tokens, as a decimal string."
        },
        "priceUsd": {
          "type": [
            "number",
            "null"
          ],
          "description": "Null = no price Chord trusts (no measured liquidity, not on the chain's board): listed last, in no total."
        },
        "valueUsd": {
          "type": [
            "number",
            "null"
          ],
          "description": "amount × priceUsd."
        },
        "change24hPct": {
          "type": [
            "number",
            "null"
          ],
          "description": "Percent."
        },
        "pnl": {
          "type": "object",
          "properties": {
            "24h": {
              "type": [
                "number",
                "null"
              ],
              "description": ""
            },
            "7d": {
              "type": [
                "number",
                "null"
              ],
              "description": ""
            },
            "30d": {
              "type": [
                "number",
                "null"
              ],
              "description": ""
            }
          },
          "description": "This token's part of each window's PnL, USD. Null = left out (a stablecoin, no price, no start price) or the chain's window is not complete.",
          "required": [
            "24h",
            "7d",
            "30d"
          ]
        }
      },
      "description": "One token a wallet holds on one chain."
    },
    "PortfolioWindow": {
      "type": "object",
      "properties": {
        "usd": {
          "type": [
            "number",
            "null"
          ],
          "description": "PnL over the window, USD. Null when the window is not complete."
        },
        "pct": {
          "type": [
            "number",
            "null"
          ],
          "description": "Percent (1.5 = +1.5 %) of the base: the value held at the window's start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete."
        },
        "complete": {
          "type": "boolean",
          "description": "The swap tape covers the whole window with no known hole. False = `usd`, `pct` and `fromTs` are null: show a dash, never a number."
        },
        "fromTs": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Unix time, milliseconds. Where the number starts: the window's start, aligned down to the hour. On `totals`: the latest start of the chains."
        }
      },
      "description": "PnL over one window by the window rule (see `GET /portfolio/{wallet}`).",
      "required": [
        "usd",
        "pct",
        "complete",
        "fromTs"
      ]
    }
  }
}