> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data sources and freshness

> Check where a value came from, when it was updated, and whether it is complete.

Add `expand=trust` to see the source, update time, and completeness of a value. Use these details when a stale or missing value would change your application's decision.

```bash theme={null}
curl -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  "https://api.0xinsider.com/api/v1/trader/swisstony?expand=trust"
```

<span id="request-it" />

## Where it is available

| Endpoint | Values described by `trust` |
| - | - |
| [Trader](/api-reference/endpoint/get-trader) and [Batch traders](/api-reference/endpoint/batch-get-traders) | P\&L, volume, market counts, win rates, grades, scores, rank, optional profile sections, and sync fields. |
| [Market snapshot](/api-reference/endpoint/get-market-snapshot) | `current_price` and `spread_bps`. |

Trader trust metadata includes `forecast_score` and `forecast_evidence`. It also describes optional sections you did not expand, with completeness set to `not_computed`.

<span id="the-shape" />

## Read one field

This example shows the metadata for `total_pnl`:

```json theme={null}
{
  "trust": {
    "total_pnl": {
      "source": {
        "kind": "provider",
        "owner": "traders",
        "field": "total_pnl"
      },
      "freshness": {
        "status": "fresh",
        "as_of": "2026-08-28T14:28:20Z"
      },
      "reconciliation": { "status": "provider_backed" },
      "completeness": { "status": "complete" }
    }
  }
}
```

| Part | Question it answers |
| - | - |
| `source` | Where did this value come from? |
| `freshness` | When was it updated, and is its age known? |
| `reconciliation` | Is it a provider value, a stored copy, or a calculation? |
| `completeness` | Does it cover everything the field promises? |

Each part always has its required status or kind. `source.owner` is also always present; `field`, `as_of`, `max_age_s`, and `detail` are omitted when unavailable.

<span id="sourcekind" />

## Source

| `source.kind` | Meaning |
| - | - |
| `provider` | Polymarket reported the value. |
| `database` | A stored 0xinsider record supplied the value. |
| `cache` | A cache supplied the value. |
| `computed` | 0xinsider calculated the value from stored facts. |
| `client_input` | Your request supplied the value. |
| `unavailable` | No source supplied the value. |

On a trader, `total_pnl`, `markets_traded`, and `total_volume` are provider values. Realized P\&L combines native realized P\&L with credited maker and taker rebates; it is a computed value, with fees already included.

<span id="freshnessstatus" />

## Freshness

| `freshness.status` | Meaning |
| - | - |
| `fresh` | An update time is known, and any defined age limit is met. |
| `refreshing` | A newer value is being fetched. |
| `stale` | The value exceeds its defined age limit. |
| `not_live` | The value describes a fixed point in time. |
| `unknown` | The age cannot be established. |
| `unavailable` | The value is unavailable. |

`as_of` is the source's update time. When `max_age_s` is present, it defines how many seconds the value can remain fresh.

Trader fields have separate clocks and no shared `max_age_s`. A `fresh` status therefore does not guarantee that a field meets your application's age limit; compare its `as_of` with that limit.

| Trader fields | Timestamp to use |
| - | - |
| `total_pnl`, `markets_traded`, and win rates | The last completed trader sync. |
| `total_volume` | The provider volume observation. |
| `grade`, `score`, `streak_tier`, and forecasting fields | The ranking calculation. |
| `rank` | The last completed leaderboard rank refresh, when known. |
| `unrealized_pnl` | The latest successful position snapshot, or the completed sync when no snapshot exists. |

Optional calculated sections such as `quant_metrics` can report `unknown` in their trust metadata. Apply the section's own documented availability rules as well; quant metrics are returned only within their 6-hour computation window.

<span id="reconciliationstatus" />

<span id="completenessstatus" />

## Reconciliation and completeness

| `reconciliation.status` | Meaning |
| - | - |
| `provider_backed` | The value is backed by a Polymarket observation. |
| `db_mirror` | The value is a stored copy rather than a new provider read for this request. |
| `computed` | The value is calculated, so no single provider field is its equivalent. |
| `partial` | Only part of the comparison was possible. |
| `not_applicable` | No comparison applies to this field. |
| `unavailable` | No comparison was possible. |

| `completeness.status` | Meaning |
| - | - |
| `complete` | The value covers its stated contract. |
| `partial` | The value covers only part of it. |
| `not_computed` | The request did not ask for this calculation or section. |
| `not_applicable` | Completeness does not apply. |
| `unavailable` | Completeness cannot be established. |

<span id="gate-an-automated-action" />

## Use it in an automated decision

1. Check that the value exists. Reject a required value whose source is `unavailable`.
2. Check completeness. Do not use `partial` or `unavailable` as a complete result.
3. Check the field's timestamp against your own age limit when one is known.
4. If age is `unknown`, decide whether your application can accept that uncertainty. Do not assume it means fresh.

<span id="what-this-does-not-tell-you" />

## Limits

Never replace an unavailable value with `0`, `[]`, or `{}`. Trust metadata explains provenance and limits; it does not guarantee a calculation is correct or predict a market result.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.