{
  "name": "Aephia Data API",
  "baseUrl": "https://api.aephia.com",
  "links": {
    "openapi": "https://api.aephia.com/openapi.json",
    "guide": "https://api.aephia.com/llms.txt",
    "catalog": "https://api.aephia.com/.well-known/api-catalog"
  },
  "authentication": "Data requests require Authorization: Bearer <token>. Use an existing Aephia Discord member API token or request a named internal project key from an Aephia administrator. There is no public key-creation endpoint. Never send keys in URLs or expose internal keys in browser code. Discovery documents are public.",
  "usage": "SAGE game statistics under /v1/sage and the explicit ship routes under /v1/ptr/sage come from the zink-ptr deployment. Universal asset supply under /v1/assets is independent mainnet-beta data. Responses are stored daily snapshots, not live chain queries. Check deployment, fetchedAt and snapshotId. Ships, Galaxy, recipes and scanning publish independently with separate snapshot IDs. Compare snapshotId before joining separately fetched Galaxy artifacts; retry if they differ. Ownership is separate from reference data. /v1/sage/galaxy/resource-statistics contains captured faction aggregates using system starbase ownership, while /v1/sage/galaxy/resource-locations is ownership-free and ranks exact raw richness descending with systemId then bodyId ties. Both cover every resource listed by /v1/sage/galaxy/resources (referenced cargo only) and are recomputed on every daily Galaxy refresh, including ownership-only changes, then stored separately under the same atomic Galaxy snapshot. Older snapshots return 503 on these new endpoints until refreshed; requests never calculate statistics or call RPC. Statistics expose captured faction-derived ownership information and may allow ownership inference even without a /v1/sage/galaxy/ownership grant; consider that exposure when granting statistics. Bigints are decimal strings; use BigInt for exact arithmetic. Only /v1/sage/galaxy/body-resources accepts ?format=compact: use /v1/sage/galaxy/body-resources?format=compact for heatmaps, with deduplicated cargo and bodies and resource tuples. Omit format for the unchanged verbose array. Both variants share snapshotId but have distinct ETags; retain validators per URL. Character Claim Stake reads at /v1/sage/characters/{character}/claim-stakes accept one planetId or systemId filter, mutually exclusive canonical nonnegative safe integer IDs. The path identifies a Character account, not a wallet. /v1/sage/planets/{bodyId}/claim-stakes and /v1/sage/star-systems/{systemId}/claim-stakes accept no queries. The definitions catalogue /v1/sage/claim-stakes/definitions accepts no queries and returns data.claimStakes and data.buildings for definitionId and buildingId joins. All three instance routes return daily ClaimStakeSnapshot arrays with bodyId/systemId in the same Galaxy generation, not live state; snapshots without Claim Stake data return 503, including current snapshots where extension acquisition, validation or sizing failed. Core Galaxy data still refreshes, with unenriched reference views. Raw IDs are deployment-specific. Unresolved body references retain both bodyId and systemId as null, the raw body reference and the complete instance in unfiltered Character reads. Planet/system groups and Character planetId/systemId filters exclude unresolved instances. Do not infer placement from lifecycle state. Full system responses add starbase.status without owner, preserving ownership in /v1/sage/galaxy/ownership. Planets add claimStakePlots: tiers carry stored base fees, not final costs, and per-definition occupied/available counts, not a tier-wide remainder. Deactivated structures still occupy plots; missing starbase-derived values stay absent. Tier definitions reference definitionId in the global catalogue. These daily summaries are not live eligibility or settlement guarantees. Unscoped keys, including existing Discord member tokens, can access all four Claim Stake routes after deployment. Planet/system groups expose ownerCharacter by location. Plot structures and chronology in reference views contain instance addresses that can be joined to those routes or public on-chain accounts to discover ownership even without an instance-route grant. Scopes are not an inference privacy boundary. These activity-dependent addresses can also change system/reference ETags. Other SAGE query parameters and pagination are unsupported. Start with the compact star-systems index and fetch individual systems; use the large full Galaxy bundle only when needed. Ship configurations expose PTR statistics mapped to mainnet identities: /v1/sage/ship-configurations, its /{id} detail, and /v1/sage/ships/{mint}/configurations use mainnet mints. The same three routes under /v1/ptr/sage use PTR mints, with no cross-namespace aliases. Ship envelopes use schemaVersion 1 and mintNamespace mainnet or ptr; deployment remains zink-ptr, the statistics source. Every row retains ptrMint and nullable catalogMint. Mainnet catalogs omit unmatched PTR ships and their IDs return 404 there. Unknown valid mints return data: [], ship: null and classBenchmarks: null, retaining global variedStats. Both per-mint views include ship identity/name/sizeClass, classBenchmarks and variedStats. Ingestion computes each size-class min/max/mean/n from one Default configuration per PTR ship, including unmatched ships and zeros; translated wrappers use value and bigint strings become numbers for derived statistics. Benchmark numbers use IEEE-754 precision and may approximate integers beyond the safe integer range; variedStats compares bigint-string values exactly and wrappers by their translated numeric value; distinct wrapper raw values with the same translated value do not vary. variedStats lists group.field paths with multiple values across all PTR configurations. Optional SDK fields remain in raw rows; only stat paths present in every configuration participate in derived statistics. Exclude misc.respawnFeeRaw only from derived statistics; raw stats and exact integer strings remain unchanged. Both views publish atomically under one snapshotId. These are PTR statistics, not mainnet gameplay statistics. Asset supply: start with /v1/assets/supply and use data[].mint in /v1/assets/{mint}/supply. Daily mainnet-beta snapshots cover all Galaxy catalog mints, including deactivated assets. supplyRaw is an exact integer string; supply is an exact unscaled decimal string (supplyRaw / 10^decimals). This is minted-minus-burned supply including treasury, unsold, escrowed and staked tokens, not circulating supply, maximum supply or cumulative issuance. Token-2022 UI multipliers and interest are not applied. Each row has decimals, tokenProgram, observedSlot and observedAt. The independent asset-supply envelope has deployment.cluster/genesisHash, source, finalized commitment and supplyDefinition, with no sdkVersion or Game. Slots may differ across batches; this is an observation window, not a single atomic chain state. Join mainnet assets by mint, never by z.ink cargo ID or presumed cross-network identity. Catalog network is reference metadata only. Invalid mint returns 400; valid mint outside the catalog 404; unavailable snapshot 503. No query parameters are supported. Recipe IDs are canonical decimal integers 0–65535; scanning region IDs are 1–65535. Recipes include active and deactivated definitions, embedded cargo, exact quantityRaw strings, and research IDs without expanded research definitions. No preferred recipe is inferred. Scanning profiles preserve repeated loot rows, rollWeight and baseQuantityRaw. Known missing profiles are null; unavailable odds retain reasons. Scan odds are SDK client-derived reference estimates: research is all-required-unlocked, exhaustionBasisPoints is 0 and focus is any. conditionalProbability is the selection share given contact; perScanProbability includes contact chance, with noContactProbability separate. Probabilities are fractions, not percentages. Join profile.loot[].cargo.id or patterns[].odds.resources[].cargo.id to recipe ingredients[].id or outputs[].id, cross-checking cargo mint and deployment cluster/Game. An empty join is valid. Across recipes and scanning compare fetchedAt and SDK/deployment metadata, not snapshotId equality; no atomic chain-slot consistency is promised. Marketplace routes under /v1/market are a separate upstream and a different contract: live Galactic Marketplace data on mainnet, not SAGE snapshots, with no snapshot envelope, no ETag and no 304. They accept days (1-92, default 30) or an explicit from/to as ISO timestamps or epoch milliseconds. Order-book points are recorded only when a book changes, so a series is irregular and a quiet market can hold no points at all across a window; anchor and lastTrade carry its last known level and sale from before the window, and the overview returns the same under anchors. Forward-fill from those rather than treating an absent day as missing data. Rows and trades are tuples in the order given by columns and tradeColumns. Prices are scaled decimals and quantities are raw units, matching between the two. The price column of a book row is the midpoint of best bid and ask, not a trade; use bestBid, bestAsk or the trade rows for what was actually paid. Both currencies are served: most resources trade in ATLAS and most ships in USDC, so a market can be empty in one and active in the other. Order-book history reaches roughly sixty days and executed sales a shorter and growing window. Local starbase markets are deliberately not exposed here.",
  "protocol": "A key may be scoped to a subset of routes, optionally restricted to named browser origins and rate limited per route. Unscoped keys reach every route. A route the key was not granted, or a request from an origin it does not allow, returns 403; exceeding the rate limit returns 429 with Retry-After. An origin restriction stops another site using the key from its own pages and cannot protect a key copied out of a bundle. GET returns JSON; HEAD returns the same status and headers without a body. OPTIONS is public CORS preflight. Send If-None-Match with the previous ETag for a 304 response. A key is required even for HEAD and conditional requests. Success uses private, no-cache; errors use no-store. Invalid or missing keys return 401; authentication or snapshot unavailability returns 503. Respect Retry-After when present. Upstream connection failures return 502 and timeouts 504. Do not retry 400/401/404/405 without correcting the request.",
  "endpoints": [
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/assets/supply",
      "summary": "Daily mainnet minted-minus-burned supply for all Galaxy catalog assets"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/assets/{mint}/supply",
      "summary": "Daily mainnet minted-minus-burned supply for one catalog mint"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/crafting/recipes",
      "summary": "Complete crafting recipe catalogue, including active and deactivated definitions; exact ingredient/output quantities are decimal strings"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/crafting/recipes/{id}",
      "summary": "One crafting recipe with ingredients, outputs, requirements and observed status"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/scanning/regions",
      "summary": "Regional scan drop profiles, policies and SDK-derived reference odds; not player-specific guarantees"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/scanning/regions/{id}",
      "summary": "One scanning region; known missing profiles remain null and unavailable odds retain their reasons"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/ship-configurations",
      "summary": "Full ship configuration catalogue in the selected mint namespace"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/ship-configurations/{id}",
      "summary": "One ship configuration by ID; unmapped ships return 404 in the mainnet view"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/ships/{mint}/configurations",
      "summary": "Configurations for a ship mint; unknown valid mints return an empty array"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/claim-stakes/definitions",
      "summary": "Daily global Claim Stake and building definitions for planet definitionId and instance buildingId joins"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/characters/{character}/claim-stakes",
      "summary": "Daily Claim Stake instances for a Character account, not a wallet; unknown valid Characters return an empty array"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/planets/{bodyId}/claim-stakes",
      "summary": "Daily Claim Stake instances across a planet; unknown planet returns 404"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/star-systems/{systemId}/claim-stakes",
      "summary": "Daily Claim Stake instances across a system; unknown system returns 404"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/star-systems",
      "summary": "Compact system index with systemId, coordinates and body counts; start here for discovery"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/star-systems/{id}",
      "summary": "One system with nested planets, asteroids and resources, starbase.status and planet claimStakePlots"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy",
      "summary": "Complete reference bundle: systems, resources, regions and kingSystems; excludes ownership and can be tens of megabytes"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/resources",
      "summary": "Deduplicated cargo definitions referenced by mineable resources"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/resource-statistics",
      "summary": "Daily global and captured-faction richness count/min/max for every referenced resource"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/resource-locations",
      "summary": "Ownership-free body locations for every referenced resource, ranked by exact richness"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/ownership",
      "summary": "Captured ownership: systems, regions, kingSystems, starbases and regionSidecars; snapshot data, not live state"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/regions",
      "summary": "Region reference tracker: geometry, membership and characteristics"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/king-systems",
      "summary": "King-system reference tracker without captured ownership"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/bodies",
      "summary": "Flat planets and asteroids with parent coordinates; excludes details.resources"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/sage/galaxy/body-resources",
      "summary": "Resource observations by bodyId and bodyAddress; join to bodies within the same snapshot"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/ptr/sage/ship-configurations",
      "summary": "PTR view: Full ship configuration catalogue in the selected mint namespace"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/ptr/sage/ship-configurations/{id}",
      "summary": "One PTR ship configuration by ID, including ships without a mainnet match"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/ptr/sage/ships/{mint}/configurations",
      "summary": "PTR view: Configurations for a ship mint; unknown valid mints return an empty array"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/market/assets/{type}",
      "summary": "Every asset of one type with its current best bid and ask in ATLAS and USDC, plus catalogue metadata and VWAP"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/market/series/{currency}/{mint}",
      "summary": "Full-resolution order book and executed sales for one market, with an anchor for markets that did not move inside the window"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/market/daily/{type}",
      "summary": "One day per point for every market of one asset type, both currencies together, with anchors for markets absent from the window"
    },
    {
      "methods": [
        "GET",
        "HEAD"
      ],
      "path": "/v1/market/tokens/{token}",
      "summary": "USD price history for a Star Atlas token at a fixed ten-minute cadence"
    }
  ],
  "otherServices": {
    "description": "These existing paths belong directly to security-bot and are outside this data API specification.",
    "paths": [
      "/health",
      "/token/validate",
      "/apitoken/interactions"
    ]
  }
}