TokenMercato node - Windows quickstart
======================================

This folder is everything you need to sell your GPU to the TokenMercato venue from
Windows. Ollama is the shortest path and the rest of this file assumes it; if
you already run llama.cpp or LM Studio, see ALREADY RUNNING SOMETHING ELSE
below. There is nothing to compile.

WHAT YOU NEED
-------------
- Node.js 22.6 or newer:  https://nodejs.org  (runs the client's TypeScript
  directly, no build step)
- Ollama:  https://ollama.com  (the inference engine that runs the weights; or
  bring your own - see ALREADY RUNNING SOMETHING ELSE)
- A provider API key from the site:  Account -> API key

SET UP OLLAMA (one time)
------------------------
1. Install Ollama and leave it running (the tray app, or run: ollama serve).
2. That's it - you do NOT have to pick a model here. After START.bat opens the
   control panel you can install, benchmark, and remove models from your browser
   with one click. (If you prefer the command line you can still pre-pull them:
   `ollama pull llama3.2:3b`, etc.)
3. Optional - measure parallel capacity. The benchmark probes how many streams
   your card decodes at once and reports it as "Lanes" beside the tok/s figure.
   The venue sends one job at a time per node today, so this does not change what
   you earn - it records what the card can do, for when the venue can use it.
   Ollama serves one request at a time per model unless you set
   OLLAMA_NUM_PARALLEL (2-4 is typical) in its environment before you start it.
   Leave it unset on a card that is already full - overcommitting VRAM slows
   every job down. The node holds the weights resident between jobs on its own
   (see "affinity" in config.toml), so you do not need OLLAMA_KEEP_ALIVE.

ALREADY RUNNING SOMETHING ELSE
------------------------------
Skip Ollama entirely if you have llama.cpp or LM Studio. Anything that serves
/v1/chat/completions works. In PowerShell, from this folder:

    .\start-backend.ps1 -Model C:\models\Llama-3.1-8B-Instruct.Q4_K_M.gguf
    .\start-backend.ps1 -LmStudio        # attach to a server LM Studio started

It waits until the server answers, then prints the [backend] block to add to
.ai-trader\config.toml (or pass -WriteConfig to have it appended for you). Leave
that window open - closing it stops the server you are selling against. vLLM
does not run natively on Windows; install it in WSL2 and use start-backend.sh.

The model name you serve has to match what the venue lists, so serve the
upstream repo name. A renamed or merged model will not match the catalog and
will not sell.

RUN IT
------
1. Open API-KEY.txt, replace the placeholder line with your account key,
   save and close it.
2. Double-click START.bat.

It registers this machine as a node (once) and starts serving. The control
panel opens in your browser right away - even with no models installed - so you
can set everything up from there. Leave the window open; press Ctrl-C to stop.
If Ollama isn't running yet, the panel still opens and tells you so; start
Ollama and install a model from the panel when you're ready.

The venue is preset to https://tokenmercato.com. If that ever changes, edit the
AITRADER_VENUE line at the top of START.bat.

CONTROL PANEL
-------------
While serving, your full control panel runs at:

    http://127.0.0.1:5100

START.bat opens it for you. From here you can:
  - Install / benchmark / remove models on this machine (with a download bar)
  - Set each model's floor price and how much capacity to rest, and turn
    selling of a model on or off
  - Let autopilot re-price you against the market. It is on from the moment
    you bench a model: it opens near what buyers are bidding, steps down
    until one fills, and stops dead at your floor. Set a floor for the whole
    card, override it on one model, or leave it blank and let each model
    price off its own rate
  - Tune affinity: how long the card stays on the model it just served, and how
    much extra the other models charge, so you are not paid to swap weights
  - Set a daily sell window (e.g. only overnight) or pause/resume selling
  - Read "Get paid more" - a live checklist of what is costing you money right
    now (offline, unlisted, priced above the book, failing, swapping too much)
  - Watch live earnings, tokens, jobs, uptime, and a searchable, sortable
    recent-jobs tape you can page through or export to CSV
It listens on localhost only - nothing outside this machine can reach it, and
your node key never leaves the process. Change the port with AITRADER_STATUS_PORT
in START.bat, or set it to 0 to turn it off.

KEEPING IT UP TO DATE
---------------------
Updates are required. When you start it, the client checks the venue for a newer
version, and if this folder is behind it updates itself before serving - it
downloads the current client, unpacks it here, and relaunches on the new version
automatically. Your API-KEY.txt and everything under .ai-trader (your key,
config, and node identity) are kept. You do not need to do anything.

If the automatic update can't run (no unzip tool on the machine), it stops
rather than serve stale code and prints a download URL - grab that zip and unpack
it over this folder by hand, keeping API-KEY.txt and .ai-trader, then start again.
You can also update on demand any time with:

    node --experimental-strip-types ai-trader.ts update

BUYING FROM THE VENUE WITH THIS FOLDER
--------------------------------------
One account both sells and buys, and this client has one buyer-side command. If
you want to point an agent tool - Cursor, Aider, an OpenAI SDK script, anything
that speaks /v1/chat/completions - at the venue, run:

    node --experimental-strip-types ai-trader.ts proxy --buyer-key sk_... --max-price 1.20

That serves an OpenAI-compatible endpoint at http://127.0.0.1:5120/v1. Set your
tool's base URL to that and its API key to anything - the proxy holds your real
key. It adds the price ceiling and the streaming the venue requires, which is
what an unmodified tool cannot send for itself. This is separate from selling;
you can run it alongside START.bat or on a machine with no GPU at all.

Two things worth knowing before you leave it running:
  - It spends real money, so it only listens on this machine, and it refuses
    anything that looks like it came from a web page - otherwise a site you
    visited could quietly run up a bill on your key. Command-line and desktop
    tools are unaffected; a tool that runs inside a browser tab will not work.
  - --max-price is your ceiling per request, in dollars per million output
    tokens. Requests that use tools (agents) have a $1.00 floor at the venue,
    which refuses them below that rather than charging you more than you asked.

TUNING
------
- Everything above is editable live from the control panel; your changes are
  saved to .ai-trader\config.overrides.json and survive a restart.
- .ai-trader\config.toml holds the shipped defaults (handle, region, models,
  floors, and the [schedule] and [affinity] blocks). The panel layers on top.
- Delete .ai-trader\config.json to forget this node and register fresh.

Your weights never leave your machine. The venue only ever sees generated text
and a verification replay.
