AVM API Reference

This section is a specification

This page describes intended AVM behavior for feature parity across implementations. It is not a wire protocol, REST schema, or statement of what any running deployment does today. Where canonical mechanics are still open, those gaps are marked explicitly rather than inferred.

The AVM API reference is a behavioral contract: what a conforming market must accept, reject, and how its state may change. Implementations may map these operations to program instructions, RPC methods, or offline simulators. The contract is chain-agnostic; transport details are out of scope.

For the curve geometry and reserve identity, see The Assured Value Machine. For feature depth, see Floor raising, Cash advance, and Call options.

Core market model

An AVM is a primary issuance and redemption engine. A market begins with zero token supply and zero reserve. Supply is elastic: issuance creates new tokens and moves supply up, while redemption destroys returned tokens and moves supply down. Capital paid on issuance enters the market reserve, which backs subsequent redemptions.

Both operations are priced by a segmented schedule y(x) defined for every supply x ≥ 0, with no upper supply bound. The schedule is continuous and monotonically non-decreasing, but it need not be smooth or strictly increase everywhere. In particular, the floor is constant, while the ramp and main segments are strictly increasing. Therefore, price never decreases as supply increases, but it does not rise at every point.

The three segments are:

• Floor — the guaranteed minimum redemption price.
• Ramp — the steeper transition between the floor and main schedule.
• Main — the long-run issuance and redemption schedule.

Contract model

Every market carries a read state and accepts operations that either apply a valid transition or reject without mutation.

Read state

Field	Meaning
floor (f)	Guaranteed minimum redemption price per token
supply (x)	Tokens outstanding
spot	Price at current supply on the active segment
reserve	Liquid capital backing the market
surplus	Backing available above the required reserve under effective-reserve accounting
x1, x2	Ramp start and ramp–main boundary
borrowed	Outstanding cash-advance balance (if enabled)

requiredReserve is the geometric area under the schedule. Cash advances do not alter that geometry. This reference does not define how a deployment accounts for advanced reserve when calculating effectiveReserve or surplus.

The curve shape combines the three segments with immutable creation slopes. Issuance and redemption move supply along that shape; only floor raises, contraction, reserve surplus deployment, or option execution may change the schedule itself.

Creation parameters (immutable)

Set once at market creation and never changed:

Parameter	Role
m2	Main schedule slope (price sensitivity)
rampScalar	Ramp steepness multiple (m1 = rampScalar × m2; typically 2)
reserveAsset	Denomination of the reserve
f0	Initial floor price (may rise later, never fall)

At launch the ramp has zero width (x1 = x2 = 0) and the curve is a single ray y = m2·x + f0.

Global invariants

Every accepted operation must preserve:

requiredReserve(x) = integral from 0 to x of y(s) ds

Buys deposit exactly the area they traverse; sells withdraw exactly the area they retrace. Invalid requests — insufficient supply, insufficient surplus, illegal floor raise, or borrow above capacity — must reject without state change.

Fees are charged at the stated settlement point. This reference names fee types but does not fix rates; rates belong to market configuration outside this contract.

Canonical fixture

The examples below share one linear market:

m2 = 0.002,  rampScalar = 2,  f0 = 0.10,  mainIntercept (b2) = 0.10

Create-market charts start from an empty state. At launch the ramp has zero width — it is not a missing drawing, the shoulder does not exist until a floor raise separates x1 from x2. Every later example uses the same market after issuance, a 10-token option exercise that shifts the live main intercept to b2 = 0.08, and an area-preserving raise to f = 0.20, so the floor, ramp, and main segments are all in view. Numbers are deterministic outputs of the documented operations, computed from hard-coded fixture inputs that stand in for user-supplied values. They illustrate the contract, not live market quotes.

Operation index

Operation	Curve shape	Primary state change
Create market	Initializes launch shape	Creation parameters persisted
Issue shares	Unchanged	Supply and reserve rise
Redeem shares	Unchanged or contracts	Supply and reserve fall
Donate reserve	Unchanged	Surplus rises
Raise floor (preserve area)	Floor rises; ramp reshapes	f rises; spot unchanged
Raise floor (surplus-funded)	Floor rises; ramp may reshape	f rises; surplus consumed
Deposit collateral	Unchanged	Collateral balance rises
Withdraw collateral	Unchanged	Collateral balance falls
Cash advance	Unchanged	Reserve out; borrowed rises
Repay advance	Unchanged	Reserve in; borrowed falls
Exercise call options	Whole schedule shifts right	Supply and floor region widen

---

Create market

Intent. Instantiate a new AVM market with immutable slopes and initial floor.

Inputs. m2, rampScalar, f0, reserveAsset, optional feature flags (call options).

Preconditions. Slopes positive; rampScalar > 1.

Transition. Persist creation parameters. Set supply = 0, reserve = 0, x1 = x2 = 0.

Invariants. Spot price equals floor at zero supply.

Reject when. Invalid parameters.

Before creation there is no market. After launch the ramp has zero width: floor and ramp coincide at the origin, and the curve is a single main ray until a floor raise opens the shoulder.

Before

No market

Floor

N/A

Spot

N/A

Supply

N/A

Reserve

N/A

After

Floor

0.1

Spot

0.1

Supply

0

Reserve

0

Floor Ramp Main Current supply

---

Issue shares

Intent. Buy new tokens along the curve (issuance).

Inputs. Exact reserve in, or exact shares out (implementations quote the paired leg).

Preconditions. Market active for issuance.

Fee. Issuance fee on the reserve leg at settlement.

Transition. Reserve increases by the integral from current supply to new supply. Supply rises. Curve shape unchanged.

Invariants. Reserve identity preserved; spot moves to y(x').

Reject when. Zero or negative amount; market issuance disabled.

Issuing with 20.00 reserve moves supply along the main segment. Floor, ramp, and main are unchanged.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

After

Floor

0.2

Spot

0.5387

Supply

229.38

Reserve

71

Floor Ramp Main Current supply

---

Redeem shares

Intent. Sell tokens back to the reserve (redemption).

Inputs. Exact shares in, or exact reserve out.

Preconditions. Sufficient outstanding supply.

Fee. Redemption fee on the reserve leg at settlement.

Transition. Reserve decreases by the retraced integral. Supply falls.

Contraction. If new supply drops below x2, the main schedule shifts down to meet the ramp at the new supply, or — if supply falls below x1 — the ramp collapses and both schedules re-anchor at (x', f).

Invariants. Reserve identity preserved.

Reject when. Insufficient supply.

Redemption without contraction

When supply stays at or above x2, only supply and reserve move.

Redeeming 30.00 shares while supply remains on the main segment. Curve shape unchanged.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

After

Floor

0.2

Spot

0.3985

Supply

159.25

Reserve

38.2

Floor Ramp Main Current supply

Redemption with contraction

When supply falls below x2 after a prior floor raise, the main schedule drops.

Selling through the ramp into the floor region. The ramp collapses; both schedules re-anchor at the new supply.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Ramp start (x1)

101.83

Ramp end (x2)

143.67

Ramp width

41.83

Main intercept (b2)

0.08

After

Floor

0.2

Spot

0.2

Supply

80

Reserve

51

Ramp start (x1)

80

Ramp end (x2)

80

Ramp width

0

Main intercept (b2)

0.06

Floor Ramp Main Current supply

---

Donate reserve

Intent. Add capital to the reserve without minting tokens (creates surplus for surplus-funded floor raises).

Inputs. Reserve amount.

Preconditions. Donation/deposit enabled for the market.

Transition. Liquid reserve rises; curve shape and supply unchanged. Surplus increases by the deposit amount.

Invariants. Required reserve unchanged; spot unchanged.

Reject when. Zero or negative amount.

Depositing 3.00 reserve without buying tokens. Surplus rises; curve geometry unchanged.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Surplus

0

After

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

54

Surplus

3

Floor Ramp Main Current supply

Curve geometry unchanged — only balances move.

---

Raise floor (preserve area)

Intent. Lift the guaranteed price by rearranging area under the existing schedule.

Inputs. Target floor f' > f (optionally explicit ramp-end witness).

Preconditions. Supply strictly above x2 (spot on the main segment).

At the economics layer, eligibility depends on schedule geometry: supply must exceed x2, and the target must admit an area-preserving reshape. Outstanding advances do not enter this geometric calculation.

Transition. Floor rises. Ramp widens and advances. Main schedule unchanged. Reserve and spot at live supply unchanged.

Invariants.

integral from 0 to x of y_new(s) ds  =  integral from 0 to x of y_old(s) ds
y_new(x) = y_old(x)

Reject when. Supply not above x2; target floor illegal.

See Floor raising for the full derivation.

Area-preserving raise from f = 0.16 to f = 0.20. The ramp widens into main-schedule territory; spot stays 0.4585 and reserve stays 51.06.

Before

Floor

0.16

Spot

0.4585

Supply

189.25

Reserve

51.06

Ramp start (x1)

67.39

Ramp end (x2)

94.77

Ramp width

27.39

Main intercept (b2)

0.08

After

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Ramp start (x1)

101.83

Ramp end (x2)

143.67

Ramp width

41.83

Main intercept (b2)

0.08

Floor Ramp Main Current supply

---

Raise floor (surplus-funded)

Intent. Lift the floor using reserve surplus rather than area rearrangement.

Inputs. Target floor f' > f.

Preconditions. Sufficient surplus to cover the increase in required reserve at live supply; live price constraint y_new(x) = y_old(x).

Transition. Floor rises. Ramp may shorten or collapse. x2 may stay fixed or advance. Surplus consumed.

Invariants. Live spot preserved; effective reserve covers new required area.

Reject when. Insufficient surplus; target floor above live spot.

Unlike the area-preserving mode, this operation does not require supply above x2. It composes with area-preserving raises when both surplus and main-segment supply are available.

---

Deposit collateral

Intent. Pledge tokens as collateral for a cash advance.

Inputs. Token amount.

Preconditions. Collateral management enabled.

Transition. Collateral balance rises. Curve, supply, and reserve unchanged.

Reject when. Zero amount.

A holder of 22.00 tokens on the main segment deposits the full position. The highlighted slice is the area under the curve for those tokens; after deposit that slice is marked deposited.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Held

22

Deposited

0

Borrowed

0

After

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Held

22

Deposited

22

Borrowed

0

Main Current supply Held Deposited Borrowed

Curve geometry unchanged — only balances move.

---

Withdraw collateral

Intent. Release pledged tokens not locked against an outstanding advance.

Inputs. Token amount.

Preconditions. Free collateral ≥ amount (pledged minus locked).

Transition. Collateral balance falls. Curve unchanged.

Reject when. Would withdraw locked collateral.

Withdrawing the full 22.00-token position before drawing an advance. The deposited slice is released completely; curve geometry and reserve remain unchanged.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Held

22

Deposited

22

Borrowed

0

After

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Held

22

Deposited

0

Borrowed

0

Main Current supply Held Deposited Borrowed

Curve geometry unchanged — only balances move.

---

Cash advance

Intent. Draw liquidity against pledged collateral at the floor value.

Inputs. Advance amount (gross of origination fee, per implementation).

Preconditions. Outstanding advance plus request ≤ pledged × f.

Fee. Flat origination fee once at draw.

Transition. Reserve pays out; borrowed balance rises. Curve and supply unchanged.

Invariants. Non-recourse; no interest accrual; no forced close-out path.

Borrowing 4.00 against deposited collateral. Capacity is 22 × 0.20 = 4.40; the darker slice is the locked portion (4 / 0.20 = 20 tokens).

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Held

22

Deposited

22

Borrowed

0

After

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

47

Held

22

Deposited

22

Borrowed

4

Main Current supply Held Deposited Borrowed

Curve geometry unchanged — only balances move.

---

Repay advance

Intent. Voluntarily repay part or all of an outstanding advance.

Inputs. Repay amount.

Preconditions. Repay amount ≤ outstanding borrowed.

Transition. Reserve receives payment; borrowed falls. Locked collateral releases proportionally. Curve unchanged.

Reject when. Repay exceeds outstanding balance.

Repaying 2.50 of the 4.00 advance. The locked slice shrinks; locked collateral falls from 20 tokens to 7.5.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

47

Held

22

Deposited

22

Borrowed

4

After

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

49.5

Held

22

Deposited

22

Borrowed

1.5

Main Current supply Held Deposited Borrowed

Curve geometry unchanged — only balances move.

---

Exercise call options

Intent. Execute perpetual call options struck at the current floor.

Inputs. Option count n.

Preconditions. Sufficient option tokens held; exercise enabled.

Fee. Execution fee on the premium above floor (per market configuration).

Transition. Buyer pays f × n into reserve. n new tokens are minted. Ramp and main translate right by n. Floor region widens. f unchanged. Spot at new supply equals spot at old supply.

Invariants.

y_new(x + n) = y_old(x)
requiredReserve_new = requiredReserve_old + f × n

See Call options.

Exercising 10 options at f = 0.20. Both schedules shift right; spot unchanged at 0.4585.

Before

Floor

0.2

Spot

0.4585

Supply

189.25

Reserve

51.06

Ramp start (x1)

101.83

Ramp end (x2)

143.67

Ramp width

41.83

Main intercept (b2)

0.08

After

Floor

0.2

Spot

0.4585

Supply

199.25

Reserve

53.06

Ramp start (x1)

111.83

Ramp end (x2)

153.67

Ramp width

41.83

Main intercept (b2)

0.06

Floor Ramp Main Current supply

---

Related

• The Assured Value Machine — curve definition and reserve identity
• Floor raising — area-preserving raises in depth
• Cash advance — capacity, locking, and repayment
• Call options — exercise economics
• The AVM as deployed today — live track comparison