# Commodity token (commodity_token)

Desk: Tokenized assets. Page: https://hedgefund.md/models/commodity_token

**What it asks.** How does a commodity token compare with futures plus cash over a hold, what band do its fees set, and can this position redeem at all?

Takes a token backed by a stored commodity: yearly drag from storage and insurance taken in units, value after the hold, the gap to a synthetic of rolled futures plus cash and the hold where they meet, the band set by mint and redeem fees and delivery cost at a size, and whether a position can redeem at all. Flat spot. Every number comes from the caller. Not a price or advice.

Results are hypothetical: arithmetic on the numbers sent, a made-up template or a stated default. Nobody achieved them, and they aren't a forecast, a recommendation, an offer or a record of real trading. Don't show any output to investors or clients, or use it to market an investment. Terms: https://hedgefund.md/terms

## Inputs

| Input | Type | Range | Required | What it is |
| --- | --- | --- | --- | --- |
| `spot_per_unit` | number | over 0 to 1000000000 | yes | Spot price of one unit of the commodity. |
| `units_per_token` | number | over 0 to 1000000 | yes | Units of the commodity behind one token today. |
| `position_value` | number | over 0 to 10000000000000 | yes | Cash put to work, in either route. |
| `storage_bps` | number | 0 to 2000 | yes | Storage cost a year, taken in units. 35 means 0.35%. |
| `insurance_bps` | number | 0 to 2000 | yes | Insurance cost a year, taken in units. 15 means 0.15%. |
| `mint_fee_bps` | number | 0 to 2000 | yes | Fee to mint, added on top of NAV. 25 means 0.25%. |
| `redeem_fee_bps` | number | 0 to 2000 | yes | Fee to redeem, taken from value. 25 means 0.25%. |
| `min_redeem_units` | number | 0 to 1000000000 | yes | Fewest units that can be redeemed. 0 means no minimum. |
| `delivery_cost` | number | 0 to 1000000000 | yes | Fixed cost of one redemption or delivery, in money. |
| `market_premium_pct` | number | -50 to 100 | yes | Market price over NAV. 1 means 1% above, -1 means 1% below. |
| `cash_rate_pct` | number | 0 to 50 | yes | Rate earned on cash held as futures collateral. 4 means 4%. |
| `futures_carry_pct` | number | -50 to 50 | yes | Yearly cost of rolling futures, positive when they sit above spot. 5 means 5%. |
| `holding_years` | number | 0 to 100 | yes | Years held. |
| `exit_discount_pct` | number | 0 to 90 | no | Optional. Discount to NAV on a market exit. It is the only exit under the minimum, and the other choice over it. Default 0, or today's discount if the market is below NAV. |

## Template

Made-up numbers that run as they stand, so you can see the shape of a result. They aren't market levels, typical values or estimates, and the names in them don't exist. Replace every number before you read anything into a run.

```json
{
  "spot_per_unit": 2000,
  "units_per_token": 0.01,
  "position_value": 250000,
  "storage_bps": 35,
  "insurance_bps": 15,
  "mint_fee_bps": 25,
  "redeem_fee_bps": 25,
  "min_redeem_units": 400,
  "delivery_cost": 1500,
  "market_premium_pct": 1.25,
  "cash_rate_pct": 4,
  "futures_carry_pct": 5,
  "holding_years": 3,
  "exit_discount_pct": 1
}
```

## What the template gives

On these numbers, the drag is 0.5% a year, the token route ends 623.29 over the synthetic after 3 years at a flat spot, they meet at 2.49 years, and the position sits under the minimum redeemable size, so its only exit is a sale, where the token's terms allow one.

- Drag a year: 0.5%
- Value after the drag: 245,655
- Synthetic's net cost a year: 1%
- Token route less synthetic at exit: 623.29
- Break-even hold: 2.4906 years
- Entry with the lower cost on these numbers: mint (watch)
- Band width at this size: no floor (breach)
- Units in the position: 124.69 (breach)

Where it flips, with the other inputs held:

- `market_premium_pct` at 0.25: Above this premium a mint costs less than a market purchase. Below it the market costs less.
- `position_value` at 802000: Under this much cash the position starts below the minimum redeemable size.
- `position_value` at 814151.3101: Under this much cash the drag takes the position below the minimum by the end of a 3 year hold.
- `futures_carry_pct` at 4.9153: At this futures carry the two routes end the hold level at a flat spot. Above it the token route ends ahead.
- `holding_years` at 2.4906: The token and the synthetic end level at this hold, at a flat spot. Longer than this the token route ends ahead.

## Formula

Drag = storage + insurance. Start value = cash / (1 + entry cost), entry cost = min(mint fee, premium). Held value = start * (1 - drag)^years. Market exit = held * (1 - exit discount). Redeem exit = held * (1 - redeem fee) - delivery cost, open only at or over the minimum. The token takes whichever exit pays more. Synthetic = cash * (1 + cash rate - futures carry)^years. Band at size S: -(redeem fee + delivery cost / S) to +mint fee.

## Assumptions

- Everything is at a flat spot, so the gap between the routes is costs alone.
- position_value is the cash put to work. Entry takes the lower cost: a mint at NAV plus the fee, or the market at NAV plus the premium. A mint fee is added on top of NAV, not taken from the tokens delivered.
- Storage and insurance are taken in units, so a holding shrinks by compounding: value = start * (1 - drag)^years. Annual compounding.
- The synthetic holds the same cash as full collateral at cash_rate_pct, against rolled futures sized to it. At a flat spot it grows by 1 + cash rate - futures carry a year, compounded annually. The cash rate counts: carry alone overstates what futures cost.
- A position with at least min_redeem_units at exit can redeem, for value * (1 - redeem fee) - delivery cost, or leave on the market, and it takes whichever pays more. A position under the minimum can only leave on the market.
- A market exit is at NAV less exit_discount_pct. Today's premium isn't counted on at exit. The default discount is today's discount if the market is below NAV, else zero, and at zero the market exit pays NAV in full, so redemption's costs don't bite. Send exit_discount_pct to price the depth a large exit would meet.
- Band at size S: from -(redeem fee + delivery cost / S) to +mint fee, around NAV. A position under the minimum has no lower edge: no redemption stands behind the market price at that size.
- Break-even hold is the first hold within 100 years where one route passes the other, by scan and bisection. Routes within 1 part in a billion of the cash count as level. Routes that start level and part at once have no break-even. When the drag takes a position under the minimum redemption closes, so the token can fall behind at a step, and the result says so.

## Not modeled

- Spot moves. The drag is on a value that moves with spot and the synthetic's carry is on its starting size, so a large move opens a gap this flat-spot figure leaves out.
- Futures margin calls, and any collateral held below full. Roll spreads, exchange fees and basis at each roll.
- Bid-ask and depth on the token's market, and how the premium moves over the hold.
- A minimum size to mint, which would close the mint route to small positions.
- Transfer costs, audits of the stored commodity, and differences in grade or location.
- Taxes, which can treat a stored commodity, a token and futures differently.
- Failure of the issuer, the vault or the futures clearing house.
- Whether this holder may acquire, hold, mint, redeem, pledge, sell or transfer this token, or use any pool. Those are legal questions for counsel.

## Call it

Every result has the same fields: summary, readings, tables, charts, flags, flips, formula, assumptions, not_modeled, hypothetical and inputs_hash. Read flags, flips and not_modeled with the summary, and pass them along together.

### HTTP

No key. The tools keep nothing you send. Send positions by POST, because a URL can land in a server log.

```bash
curl -s https://hedgefund.md/api/v1/commodity_token \
  -H 'content-type: application/json' \
  -d '{"spot_per_unit":2000,"units_per_token":0.01,"position_value":250000,"storage_bps":35,"insurance_bps":15,"mint_fee_bps":25,"redeem_fee_bps":25,"min_redeem_units":400,"delivery_cost":1500,"market_premium_pct":1.25,"cash_rate_pct":4,"futures_carry_pct":5,"holding_years":3,"exit_discount_pct":1}' \
  | jq '{summary, flags, flips, not_modeled, inputs_hash}'
```

### MCP

The tool is `commodity_token` on the server at https://hedgefund.md/mcp.

```bash
curl -s https://hedgefund.md/mcp \
  -H 'content-type: application/json' -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commodity_token","arguments":{"spot_per_unit":2000,"units_per_token":0.01,"position_value":250000,"storage_bps":35,"insurance_bps":15,"mint_fee_bps":25,"redeem_fee_bps":25,"min_redeem_units":400,"delivery_cost":1500,"market_premium_pct":1.25,"cash_rate_pct":4,"futures_carry_pct":5,"holding_years":3,"exit_discount_pct":1}}}' \
  | jq '.result.structuredContent | {summary, flags, flips, not_modeled, inputs_hash}'
```

### The library

The same code on your own machine, with no dependencies, and nothing is sent anywhere.

```bash
curl -fsSL https://hedgefund.md/hedgefund.mjs -o hedgefund.mjs   # read it before you run it
node hedgefund.mjs template commodity_token > mine.json           # replace every number in it
node hedgefund.mjs run commodity_token mine.json | jq '{summary, flags, flips, not_modeled, inputs_hash}'
```

In a script:

```js
import { run, template } from "./hedgefund.mjs";

const inputs = template("commodity_token"); // replace every number in it
const { summary, flags, flips, not_modeled } = run("commodity_token", inputs);
```