Token Machine, live stream stocks, map, and block chain ledger app

Token Trade Calculator

Quick start checklist (one-line)

1. Set tokens → 2. Enter size & prices → 3. Enter realistic fees/slippage/xfer → 4. Click check → 5. Verify orderbooks & latency → 6. Pilot trade → 7. Scale if successful.

Tokens Trade Calculator — Comprehensive User Guide

Thanks — this guide walks through every action in the HTML Tokens Trade Calculator you provided, explains what each input means, gives step-by-step procedures for using the two main workflows (Arbitrage and Pullback Rotation), shows a numeric worked example (using the app’s default values), lists failure modes and troubleshooting, and finishes with a ready-to-use pre-trade checklist and glossary. This is for education only — always test with small amounts and on paper/simulations first.

1 — Overview (what this app does)

• Purpose: educational calculator to spot simple arbitrage opportunities between two markets (or two exchanges/venues) for the same base token, and to generate rotation signals (pullback/TP) on a single market.

• Units: The app is label-agnostic — you name the tokens. Internally it uses the quote-per-base convention (price = quote token units per 1 base token) unless you choose the other convention (the UI lets you flip it).

• Two workflows:

  1. Arbitrage between two markets — simulates selling base → quote in one market and buying base back in the other, factoring fees, slippage and transfer cost; provides net P&L in base tokens and whether the spread meets your threshold.

  2. Pullback rotation on one market — signals BUY/HOLD/SELL based on change from entry, pullback from recent peak, and your take-profit / re-entry thresholds.

2 — Element-by-element explanation (exactly what each control does)

Top labels / global

• Token₁ name (baseName) — label for the asset you are trying to end up with. Example: BTC, ETH, USDC. The calculator expresses final P&L in this token.

• Token₂ name (quoteName) — the quoted currency used to price the base token (e.g., USD, USDC, BTC if base is ETH).

• Quote convention (quoteConv)

  • Price = Token₂ per Token₁ (default): quote-per-base (QPERB). Example: 7.10 USD per Token₁.

  • Price = Token₁ per Token₂: base-per-quote (BPERQ). If you choose this, the app internally converts to QPERB for calculations.

• Trade size (size) — how much base token you start with (the quantity you will sell on leg 1). Must be > 0.

Arbitrage inputs (Market A/B)

• Market A Price (pxA) — price of base in market A (see convention).

• Market B Price (pxB) — price of base in market B.

• Total round-trip fee (%) (fee) — total fees expressed as percent of the base amount on a round trip. Implementation note: the app treats this as a percentage of the base amount applied on each side in its model (first leg fee reduces base you start with; second leg fee is applied to base received back).

• Slippage per leg (%) (slip) — expected execution slippage per leg. The app uses sell price = bestPrice (1 - slip) and buy price = bestPrice (1 + slip).

• Transfer cost (xfer) — any fixed cost (in quote units) required to transfer the quote token from one venue to the other (e.g., blockchain transfer fees denominated in the quote). This is subtracted from the quote before re-buying base.

• Minimum spread to trade (%) (thresh) — the minimum gross spread you require to consider the trade worth opening (the app compares absolute % spread to this value).

Arbitrage output

• Spread — computed as (A - B) / ((A + B)/2) * 100% (midpoint basis). Displays route (A→B or B→A).

• Leg prices (adjusted for slippage).

• Net — final P&L in base (base_back - base_start) and P&L percent.

• Indication — whether spread meets threshold.

Pullback / rotation inputs

• Current price (curPx) — current market price.

• Last entry price (entryPx) — price you last entered at (or the price from which you measure performance).

• Peak since entry (peakPx) — highest observed price since entry (used to measure pullback).

• Take-profit % (tpPct) — if the price is up by ≥ this from entry, signal to sell (take profit).

• Re-entry pullback % (rePct) — if price has pulled back from its peak by ≥ this amount, signal to buy back in.

• Fee per leg (%) (fee2) — used to show approximate round-trip fees for a rotation signal (round-trip shown as 2× fee2).

Pullback output

• Signal — HOLD, SELL base → quote, or BUY base with quote with short hint lines (Δ from entry, pullback from peak, approx. round-trip fees).

3 — Step-by-step "How to use" (Arbitrage)

Goal: Start with size base tokens and finish with more than size.

1. Name tokens: Set Token₁ (base) and Token₂ (quote). Choose the correct Quote convention to match how your price quotes appear.

2. Set trade size: Enter how many base tokens you will attempt to arbitrage (start small on live).

3. Enter market prices for market A and market B (bid/ask midpoint or best executable price depending on how conservative you are).

4. Set fees & slippage:

   • fee = total expected round-trip fee as a percentage (include exchange taker/maker fees, swap fees, and any conversion fees). Example: 0.20 means 0.20% (0.002 as fraction).

   • slip = expected slippage per leg (use 0.05% = 0.05 if field expects percent — the app divides by 100 internally).

   • xfer = any fixed transfer fee in quote units (e.g., $3 stablecoin bridge fee → enter 3).

5. Set minimum spread (thresh) — your minimum acceptable gross spread to attempt a trade (this is a policy threshold to filter false positives).

6. Click “Check opportunity”.

7. Read output carefully:

   • Confirm the route (sell where price higher, buy where price lower).

   • Check Leg 1 and Leg 2 adjusted prices (includes slippage).

   • Check Net in base tokens and percent.

   • If Meets threshold, then re-confirm real orderbook depth & fees before trading.

Key confirmation steps before executing:

• Verify orderbook depth at the sizes you plan to trade (slippage may be worse).

• Confirm settlement/transfer latency and counterparty risk — an arbitrage that looks good in the calculator can disappear if transfers are slow.

• Ensure you cannot be frontrun or MEV-squeezed in the venue or chain you use.

• If you need to move assets between venues, confirm transfer times and how price may move during transfer.

4 — Step-by-step "How to use" (Pullback rotation)

Goal: Rotate between base and quote on a single market based on strength and pullbacks.

1. Set the token names and convention.

2. Enter Current / Entry / Peak prices.

   • entryPx = price you entered (or plan to enter).

   • peakPx = highest price observed since you entered (for measuring pullback from peak).

3. Set take-profit (tpPct) and re-entry pullback (rePct) that match your risk appetite and trading style.

4. Set fee per leg (fee2) so you know the trade cost.

5. Click “Get signal”.

6. Interpretation:

   • If Δ from entry ≥ TP, signal SELL (lock profits).

   • Else if Pullback from peak ≥ RE, signal BUY (re-entry opportunity).

   • Otherwise, HOLD.

Notes:

• Use peak carefully — it must be updated regularly to reflect true local maxima.

• Consider partial take-profits or staggered re-entries to manage risk.

• The tool outputs only signal — you must confirm liquidity & fees.

5 — Worked numeric example (exact calculations using the app defaults)

Inputs used (defaults from the HTML):

• base = Token₁, quote = Token₂

• size = 1000 (base units)

• pxA = 7.1000, pxB = 7.0200 (quote-per-base)

• fee (round trip) = 0.20% → feePct = 0.002 (fraction)

• slip = 0.05% → slip = 0.0005 (fraction)

• xfer = 0 (no fixed quote transfer fee)

• thresh = 0.60%

Step-by-step arithmetic (same logic as app):

1. Normalize to internal convention QPERB (no change here).

2. Mid price = (7.1000 + 7.0200) / 2 = 7.0600.Spread (%) = (A - B) / mid 100 = (7.1000 - 7.0200) / 7.0600 100 ≈ 1.1331444759%.

3. Slippage-adjusted leg prices:

   • sellAt = max(A,B) (1 - slip) = 7.1000 (1 - 0.0005) = 7.09645.

   • buyAt = min(A,B) (1 + slip) = 7.0200 (1 + 0.0005) = 7.02351.

4. Round-trip fee applied naively to base:

   • fee1 = size feePct = 1000 0.002 = 2.0 base (this reduces base before leg 1).

   • sizeAfterFee1 = 1000 - 2.0 = 998.0 base.

5. Leg 1 (sell base → quote):

   • quoteOut = sizeAfterFee1 sellAt = 998.0 7.09645 = 7,082.2571 quote units.

6. Transfer cost xfer = 0 so quote remains 7,082.2571.

7. Leg 2 (buy base back):

   • baseBackGross = quoteAfterXfer / buyAt = 7082.2571 / 7.02351 ≈ 1008.3643505882387 base.

   • fee2 = baseBackGross feePct ≈ 1008.3643505882387 0.002 ≈ 2.0167287011764774 base.

   • baseBack = baseBackGross - fee2 ≈ 1006.3476218870622 base.

8. P&L = baseBack - size = 1006.3476218870622 - 1000 = +6.347621887062246 base.

   • P&L % = 6.347621887062246 / 1000 * 100 = 0.6347621887062246%.

Result interpretation:

• Gross spread ≈ 1.133%.

• After slippage and fees the net P&L ≈ +6.348 base (≈ +0.635%).

• The threshold was 0.60% → meets threshold (so the app will mark it as an opportunity).

Important: this worked example uses the app’s fee model (a flat percent of base each leg) and simple slippage assumptions. Real execution costs, orderbook depth, and transfer timings often materially change outcomes.

6 — Common pitfalls & failure modes (and how to avoid them)

1. Ignoring orderbook depth: quoted mid prices are meaningless if your intended size consumes multiple levels. Check the orderbook and simulate market impact at the intended size before executing.

2. Underestimating slippage: low displayed slippage can hide liquidity gaps. Use conservative slippage estimates for initial runs.

3. Transfer latency & price movement: if you must move assets between venues, price can move during transfer and wipe profit (or turn profitable trades into losses). Use cross-venue atomic mechanisms where possible.

4. Mis-specified fees: many places charge maker/taker differences, conversion fees, or withdrawal fees in separate tokens. Convert all fee types into the same unit (the calculator expects percentages or fixed quote transfer amounts).

5. Frontrunning / MEV / sandwich attacks: especially on public-chain DEXs; be cautious with large trades and on congested chains.

6. Fee model mismatch: this tool uses a simplified fee model—if your exchange charges fees in quote rather than base, or has tiered fee schedules, convert those precisely into the fields.

7. Ignoring slippage asymmetry: sometimes selling causes more slippage than buying (or vice versa); if so enter larger slip numbers or model asymmetry manually (e.g., run two tests with higher slip on the more illiquid leg).

8. Rounding/precision with tiny tokens: for tokens with tiny unit values or large decimals, ensure sizes and step values are appropriate.

7 — Advanced tips & tricks

• Orderbook simulation: before committing, take a snapshot of book depth and compute a real execution-weighted average price for the quantity you intend to trade — then plug those execution prices into pxA/pxB and re-run the calculator.

• Partial fills & staged execution: consider executing in staggered slices to reduce market impact. Recalculate for smaller slice sizes.

• On-chain: use gas/priority estimation as part of xfer (if transfer cost is paid in gas / quote). Convert gas to quote units.

• Time-of-day effects: liquidity can vary with timezones — create conservative thresholds for thin hours.

• Hedging vs Arbitrage: if you can’t transfer quickly, consider a hedged synthetic position (like entering a futures trade) to lock the spread.

• Add margin for slippage/fees: set thresh slightly higher than breakeven to account for hidden costs.

8 — Troubleshooting (if the app shows unexpected results)

• No output when clicking “Check opportunity”: ensure numeric fields contain positive numbers and size > 0. The JS early-exits if invalid inputs are detected.

• Zero or NaN results: check you didn’t enter zero for a price or set buyAt to 0 after converting conventions (division by zero).

• Large negative P&L despite apparent spread: re-check fee and slippage inputs and confirm whether one price needs to be inverted (you might have set the wrong quote convention).

• Signal conflicts in rotation tool: make sure peakPx is indeed the historical peak since you entered; a stale peak can produce incorrect pullback numbers.

9 — Practical pre-trade checklist (copy this before every real trade)

1.  Confirm token names and quote convention are correct.

2.  Check live orderbooks at both venues for depth at intended size.

3.  Recompute execution-weighted prices and plug into pxA/pxB.

4.  Verify fee includes all fees (maker/taker, swap, withdrawal, conversion).

5.  Set slip conservatively for the venue and size.

6.  Enter any fixed xfer cost in quote units.

7.  Use the app to compute net P&L; ensure net P&L > buffer margin above threshold.

8.  Confirm settlement/transfer times and market risk during transfer.

9.  If profitable on paper, run a very small pilot trade (1–5% of planned size).

10.  If pilot succeeds, scale carefully and monitor live.

10 — Example operational SOP (simple, concrete)

Scenario: You see a 1.2% spread between Exchange A (7.20) and Exchange B (7.10) for Token₁/USDC and you want to try an arbitrage.

1. Enter tokens, size = 1000 base.

2. Enter pxA = 7.20, pxB = 7.10, fee = 0.40% (0.40), slip = 0.15% (0.15), xfer = 1.5 (USDC), thresh = 0.70%.

3. Click Check opportunity and note net P&L.

4. If P&L > 0.70% and orderbook supports size, place immediate limit/taker orders as required (sell where price is higher).

5. If transfer needed, execute hedge (e.g., offsetting futures position) to lock exposure. Monitor until funds arrive; close hedge after arbitrage completion.

6. Log trade, fees, and final realized P&L. Update your model parameters if realized slippage was different.

11 — FAQ (short)

Q: Are the calculator outputs guarantees?A: No. These are simulations based on your inputs. Real execution may differ due to latency, hidden fees, and market behavior.

Q: Where should I set thresh?A: Depends on size and risk. For small retail trades with modest fees, 0.5–1.0% may be reasonable; for larger trades, increase threshold to cover market impact and transfer risk.

Q: Does the app assume fees are charged in base?A: For simplicity the app models fees as percentages of base (as implemented). If your venue charges fees differently, convert them into an equivalent % of base or include fixed quote transfer in xfer.

12 — Glossary (short)

• Base: the asset you are trading (Token₁).

• Quote: the currency used to price the base (Token₂).

• QPERB: Quote Per Base (price = quote units / 1 base).

• Slippage: expected price movement between viewing and execution.

• Orderbook depth: quantity available at each price level; impacts slippage.

• MEV / frontrun: miner/executor value extraction that can cost you profit on-chain.

13 — Embedding & deployment tips

• You already included an iframe snippet in the HTML footer. To embed:<iframe src="tokens_trade_calculator.html" width="100%" height="680" frameborder="0"></iframe>

• Host the file securely and use HTTPS so embedded iframes load across sites without mixed-content issues.

• Consider adding a CSV export / logging feature to record inputs and results for auditing and parameter tuning.

14 — Final safety & ethics note

• This tool is educational only. Trading involves risk, including total loss. Always comply with local laws and exchange terms. Test strategies on paper or in testnets before allocating meaningful capital.