airstreetDocs
Introduction

End-to-end: $TOKYO × Tokyo Residential

One Pair Market traced from the creator’s first click to a holder’s claim. Every number is worked through, and every number reconciles.

ILLUSTRATIVE

The setup

A creator wants to launch a coin about Tokyo and pair it with Tokyo’s residential property market. In PairStreet terms that is a Pair MarketPair MarketThe canonical pairing of an internet asset with a financial Pair: TOKEN × PAIR INSTRUMENT, plus the Pair Vault, configuration and accounting that connect them.: TOKEN × PAIR INSTRUMENT, $TOKYO × Tokyo Residential. The coin launches and trades on Pump. PairStreet attaches the Pair: the Pair InstrumentPair InstrumentThe financial exposure a Pair Market is paired with, such as Tokyo Residential or Swiss Government Debt. A catalog object with a provider, an eligibility policy and a status., the Pair VaultPair VaultThe account that receives settlement value allocated to one Pair Market, holds it until conversion, and holds the acquired Pair Asset until it is allocated to holders. that accumulates value for it, the Pair RouterPair RouterThe execution layer that converts a Pair Vault's settlement balance into an acquisition plan for the Pair Asset and hands it to the right executor. that acquires its Pair AssetPair AssetThe transferable onchain asset the implementation acquires and distributes for a Pair Instrument. Holders receive the Pair Asset, not the reference market itself., and the reward epochs that deliver that asset to holders.

Tokyo Residential is a Pair Instrument representing the target financial exposure configured for the Pair Market: Tokyo condominiums and rental housing across the 23 wards, tracked as a residential real-estate basket. Holders of $TOKYO never receive Tokyo property. In this example they receive TYO.RES, the transferable onchain Pair Asset the instrument’s provider route delivers.

Scroll the steps below. The scene on the right follows each stage.

  1. 01 · LAUNCH
    The creator prepares $TOKYO

    The creator fills in the name, symbol, image and socials, then opens the instrument picker and chooses Tokyo Residential. The Eligibility Engine checks the creator’s region against the instrument’s rules before the launch is built. PairStreet stores the image and an immutable metadata JSON served at /api/metadata/<id>.

    Coin
    $TOKYO
    Pair Instrument
    Tokyo Residential
    Category · country
    real_estate · JP
    Optional first buy
    2 SOL
  2. 02 · LAUNCH
    Three transactions, one wallet prompt

    PairStreet builds up to three transactions and the creator signs them together. The first creates the coin and its fee-sharing config. The second sets the shares and locks them. The third is the first buy, with the 0.5% PairStreet fee in the same transaction. Pump and Solana covers each instruction.

    Tx 1
    create_v2 + create_fee_sharing_config
    Tx 2
    update_fee_shares 5,000 / 5,000 bps
    Tx 3
    buy 1.99 SOL + 0.01 SOL fee
    Fee config
    locked (adminRevoked)
  3. 03 · PAIR
    The Pair Market is registered

    /api/launch/confirm verifies the launch on-chain (mint and creator in the transaction, bonding curve present), registers the Pair Market in the Pair Registry and reads the fee split back from chain. The activity feed records TOKEN_CREATED and PAIR_SELECTED. In this example the Tokyo Residential route and Pair Vault custody are active, so the market settles on a schedule.

    Pair Market
    $TOKYO × Tokyo Residential
    Fee split status
    locked
    Reward methodology
    time_weighted_balance
    Exclusions
    creator, vault, liquidity
  4. 04 · FLOW
    Trading generates creator fees

    $TOKYO trades on its Pump bonding curve. Pump accrues the coin’s creator fees to the fee-sharing config, and anyone can pay them out with distribute_creator_fees. The locked split sends half to the creator and half to the treasury, where it is accounted as protocol revenue and the market’s Pair Vault reserve. The example assumes creator fees equal 0.25% of volume.

    Cumulative volume
    $32,000,000
    Creator fees (0.25%, assumed)
    $80,000
    Creator, 50%
    $40,000
    Protocol revenue, 25%
    $20,000
    Pair Vault reserve, 25%
    $20,000
  5. 05 · VAULT
    The Pair Vault is funded

    The $20,000 reserve funds the $TOKYO Pair Vault as a USDC settlement balance. The funding is written as a pair_vault_fundings row and a PAIR_VAULT_FUNDED event. This balance belongs to the Pair; it is not protocol revenue.

    Settlement asset
    USDC
    Pair allocation accumulated
    $20,000.00
    Source
    creator_fees
  6. 06 · SETTLE
    Settlement opens and the router plans

    At the market’s settlement time, runSettlement opens settlement sequence 1 and hands the vault balance to the Pair Router. The router asks the instrument’s provider for a route and computes the execution cost of acquiring the Pair Asset.

    Settlement balance
    $20,000.00
    Execution cost
    $35.00
    Net acquisition
    $19,965.00
    Status
    planning
  7. 07 · SETTLE
    The provider quotes

    The provider returns an InstrumentQuote for 19,965 USDC in: 776.84 TYO.RES out. The quote implies a price of $25.70 per unit. The route carries no blockers, so the plan moves to execution.

    Input
    19,965 USDC
    Output
    776.84 TYO.RES
    Implied price
    $25.70 / unit
    Blockers
    none
  8. 08 · ASSET
    The Pair Asset is purchased

    The router executes. 776.84 TYO.RES arrive in the $TOKYO Pair Vault. The purchase is written to pair_purchases, the settlement moves to completed, and the feed records PAIR_ASSET_PURCHASED and PAIR_SETTLEMENT.

    Pair Asset acquired
    776.84 TYO.RES
    Acquired, lifetime
    $19,965.00
    Settlements count
    1
  9. 09 · ASSET
    Pair Value updates

    Pair ValuePair ValueThe current tracked value of Pair Assets associated with a Pair Market according to PairStreet accounting: Σ quantity × reference price. Independent of the token's market cap. is quantity × reference price for the Pair Asset held for the market. Marked at $25.70, the vault’s 776.84 units read $19,964.79. The $0.21 gap to the $19,965 spent is the price rounded to cents. Pair Value is independent of $TOKYO’s market cap.

    Quantity
    776.84 TYO.RES
    Reference price
    $25.70
    Pair Value
    $19,964.79
  10. 10 · EPOCH
    A reward epoch opens

    The settlement funds a Reward EpochReward EpochA window over which acquired Pair Asset is allocated to eligible holders by their holder weight. Produces exact integer allocations and a Merkle root.. This example releases the full acquisition into one epoch (epochReleaseBps 10,000). Each eligible holder’s weight is balance × hours held inside the epoch. The creator, the vault and liquidity accounts are excluded.

    Reward pool
    776.84 TYO.RES
    Methodology
    time_weighted_balance
    Eligible holder weight
    12,800,000 token-hours
  11. 11 · EPOCH
    Holders receive allocations

    Wallet A held 40,000 $TOKYO for 16 hours of the epoch: 640,000 token-hours, exactly 5% of the eligible weight. Its allocation is 5% of the pool. The engine allocates in integer base units with the largest-remainder method, so allocations sum to the pool exactly, and computes a Merkle root over every allocation.

    Wallet A weight
    640,000 token-hours
    Wallet A share
    5.000%
    Wallet A allocation
    38.842 TYO.RES
  12. 12 · CLAIM
    Wallet A claims

    Wallet A claims through POST /api/rewards/claim. The claim checks the wallet’s region against the instrument’s rules, pays out once, and moves 38.842 TYO.RES from the Pair Vault to Wallet A. The feed records PAIR_REWARD_CLAIMED. The other holders’ 737.998 units stay claimable in the vault.

    Claimed to Wallet A
    38.842 TYO.RES
    Value at $25.70
    $998.24
    Still claimable
    737.998 TYO.RES

Every number in one table

The full chain, top to bottom. Each row follows from the rows above it.

All case study numbers
QuantityValueHow it is derived
Cumulative $TOKYO volume$32,000,000Assumed, so that the reserve reaches $20,000
Creator-fee rate0.25%Assumption; Pump sets the rate per market
Creator fees$80,000$32,000,000 × 0.25%
Creator share$40,000$80,000 × 50%
Protocol revenue share$20,000$80,000 × 25%
Pair allocation accumulated$20,000$80,000 × 25% (Pair Vault reserve)
Execution cost$35Provider route cost, 0.175% of $20,000
Net acquisition$19,965$20,000 − $35
Pair Asset acquired776.84 TYO.RESProvider quote
Implied price$25.70 per unit$19,965 ÷ 776.84 = 25.7003
Pair Value after purchase$19,964.79776.84 × $25.70
Eligible holder weight12,800,000 token-hoursΣ balance × hours, eligible holders only
Wallet A weight640,000 token-hours40,000 $TOKYO × 16 hours
Wallet A share5%640,000 ÷ 12,800,000
Wallet A reward38.842 TYO.RES5% × 776.84
Remaining claimable737.998 TYO.RES776.84 − 38.842

The reward math

The holder side of the example is three lines.

share(A) = 640,000 ÷ 12,800,000 = 0.05 = 5%
reward(A) = 0.05 × 776.84 TYO.RES = 38.842 TYO.RES
Σ rewards = 776.84 TYO.RES (largest-remainder allocation, exact)
Wallet A’s share is its weight over the eligible weight; its reward is that share of the pool.

And the Pair side, from volume to units:

creator fees = $20,000 ÷ 0.25 = $80,000
volume = $80,000 ÷ 0.0025 = $32,000,000
price = ($20,000 − $35) ÷ 776.84 TYO.RES = $25.7003 ≈ $25.70 per unit
Assumption: creator fees equal 0.25% of trading volume. The Pair Vault reserve is 25% of creator fees.

The PairStreet 0.5% trading fee is a separate stream. If all $32,000,000 of volume were routed through PairStreet it would add $160,000 of protocol revenue; none of it enters the Pair Vault. See Protocol Economics.

What to read next

  • ·How Pairing Works: the same lifecycle as reference steps rather than a story.
  • ·Pair Vault and Settlement: how the $20,000 is held and converted.
  • ·Pair Value: why $19,964.79 is not a market cap.
  • ·Holder Rewards: time-weighted balance, largest-remainder allocation and Merkle claims.
  • ·Status: which settlement routes are active on mainnet today.