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

# Defining Virtual Assets

> Declare an asset once, pick how its rate is priced, and use it across every account in your project.

<Note>
  Applies to **Program-Funded** programs. See [Overview](/virtual-assets/overview) for the bigger picture.
</Note>

A **virtual asset definition** describes a single unit of value you want Reap to track. Once defined, you can [post deposits, withdrawals, and settlements](/virtual-assets/postings) against it on any account in the project. Each account can hold balances in multiple virtual assets at once, and their combined value (in your program's billing currency) contributes to the account's available balance.

You decide what a virtual asset represents. Stablecoins, non-stable crypto, yield-bearing share tokens, fiat-backed units, points, cashback, and program credits all work through the same primitive: a symbol, a decimal precision, and a way to price it in your program's billing currency.

## Anatomy of a definition

| Field        | What it is                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| `symbol`     | Short uppercase identifier for the asset (e.g. `USDC`, `BTC`, `GOLD`, `POINTS`).                     |
| `name`       | Human-readable name (e.g. "USD Coin").                                                               |
| `decimals`   | Number of decimal places. Match what you use on your side so you never deal with rounding surprises. |
| `rateSource` | `FIXED` or `HTTP`. Determines how the rate is priced. See below.                                     |
| `status`     | `ACTIVE` or `DISABLED`. Disabled assets are excluded from balance computation.                       |

Create a virtual asset via [`POST /virtual-assets`](/api-reference/virtual-assets/create-virtual-asset). Update its name or HTTP endpoint via [`PATCH /virtual-assets/:id`](/api-reference/virtual-assets/update-virtual-asset).

<Tip>
  Pick the `symbol` carefully. It surfaces in the account assets breakdown, in the postings payload, and in webhook events. It cannot be changed once the asset is created.
</Tip>

## Rate sources

Every virtual asset has an exchange rate in your program's billing currency. The rate determines how the asset's raw units translate into that currency for balance computation and authorization.

Reap supports two rate sources:

<CardGroup cols={2}>
  <Card title="FIXED" icon="lock">
    You set the rate, Reap stores it. The rate stays constant until you explicitly update it. Best for stable or client-priced units (USD-denominated credits, loyalty points, internal reference prices).
  </Card>

  <Card title="HTTP" icon="globe">
    Reap polls an endpoint you host. The rate updates whenever your endpoint returns a new value. Best for assets priced against a moving market you already have data for (volatile crypto, FX rates, NAV).
  </Card>
</CardGroup>

Choose per asset. A project can mix both.

### FIXED

Set the initial rate when you create the asset. Update it any time via [`PUT /virtual-assets/:id/rate`](/api-reference/virtual-assets/set-rate-for-virtual-asset). The update takes effect immediately for balance computation.

Typical values:

* `1.00` for a USD-denominated credit like cashback, sign-up bonus, or credit line.
* `0.01` for a point system (one hundred points per USD).
* Any other ratio you want to peg, like a fixed internal conversion for a stablecoin you custody.

Every rate change is stored as a snapshot with a timestamp. Past balances always recompute against the rate that was active at the time the snapshot was taken.

### HTTP

Provide an endpoint URL when you create the asset. Reap polls it every **5 minutes** and stores each new value as a rate snapshot. Card authorizations use the most recent snapshot, not a live fetch. Your endpoint must respond to a `GET` request with this JSON:

```json theme={null}
{ "rate": 3487.42 }
```

Where `rate` is the value of one unit of the virtual asset in your program's billing currency. On creation, Reap fetches your endpoint synchronously to validate it. If the endpoint is unreachable or returns an invalid response, the asset is not created.

<Warning>
  Your endpoint should return quickly (within a few seconds) and should not require authentication. Reap caches the most recent successful rate, so transient failures do not stall spending, but prolonged outages will leave balances priced at the last known rate until the endpoint recovers.
</Warning>

You can point the endpoint at anything: your market data service, a cached feed from a pricing provider, a simple proxy to an upstream API. Reap does not prescribe the source.

Update the endpoint URL any time via [`PATCH /virtual-assets/:id`](/api-reference/virtual-assets/update-virtual-asset).

### When to choose which

<AccordionGroup>
  <Accordion title="Use FIXED when...">
    * The unit is priced in USD already (credits, cashback, allowances).
    * The rate is pegged by program design, not by market movement.
    * You want deterministic rate changes tied to explicit business decisions.
  </Accordion>

  <Accordion title="Use HTTP when...">
    * The asset tracks a volatile underlying (BTC, ETH, other tokens).
    * The asset is a yield-bearing share token whose USD value drifts continuously (vault shares, LST/LRT tokens, money-market deposit receipts). Point the endpoint at whatever source you trust for the live share price.
    * You already have a pricing pipeline and do not want to push updates every time a price ticks.
    * The rate should reflect your platform's live price, not a manual snapshot.
  </Accordion>
</AccordionGroup>

## Lifecycle

```mermaid theme={null}
flowchart LR
    C[Create] --> A[ACTIVE]
    A -->|PATCH /virtual-assets/:id<br/>status=DISABLED| D[DISABLED]
```

* **Create.** Defines the asset, validates the rate source (fetches once for HTTP, stores the initial rate for FIXED), activates it. The asset can now receive allocations.
* **Update.** You can edit `name` and, for HTTP assets, `httpEndpoint`. The `symbol`, `decimals`, and `rateSource` are immutable.
* **Set rate.** Available only for FIXED assets. Inserts a new rate snapshot.
* **Disable.** One-way. Disabled assets cannot receive new allocations, and their existing balances are excluded from available balance. Historical entries remain on the ledger for audit.

<Warning>
  Disabling a virtual asset is permanent. If users still hold non-zero balances in that asset, their available balance will drop immediately. [Settle](/virtual-assets/postings#settling-card-debt) or [withdraw](/virtual-assets/postings) outstanding balances before disabling if you need to wind the asset down cleanly.
</Warning>