TokenMercato node - Linux and macOS
===================================

This folder is everything you need to sell your GPU's idle time to the
TokenMercato venue. There is nothing to compile.

If you got here from the one-line installer, `ai-trader` is already on your
PATH and you can skip to RUN IT.

WHAT YOU NEED
-------------
- Node.js 22.6 or newer:  https://nodejs.org  (runs the client's TypeScript
  directly, no build step)
- An inference server on this machine. Ollama (https://ollama.com) is the
  shortest path and the rest of this file assumes it; anything serving
  /v1/chat/completions works - see ALREADY RUNNING SOMETHING ELSE.
- An account key from the site:  Account -> API key

SET UP OLLAMA (one time)
------------------------
1. Install Ollama and leave it running (`ollama serve`, or the menu-bar app on
   macOS).
2. That's it - you do NOT have to pick a model here. Once the control panel is
   open you can install, benchmark, and remove models from your browser with
   one click. (`ollama pull qwen3.5:4b` still works if you prefer.)
3. Optional - measure parallel capacity. The benchmark probes how many streams
   your card decodes at once and reports it as "Lanes". 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) before starting 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" below), so you do not need
   OLLAMA_KEEP_ALIVE.

ALREADY RUNNING SOMETHING ELSE
------------------------------
Skip Ollama if you have vLLM or llama.cpp. From this folder:

    ./start-backend.sh --model meta-llama/Llama-3.1-8B-Instruct
    ./start-backend.sh --model ./llama-3.1-8b-instruct.Q4_K_M.gguf --runtime llama-cpp

It waits until the server answers, then prints the [backend] block to add to
~/.ai-trader/config.toml (or pass --write-config to have it appended for you).
Leave that shell open - closing it stops the server you are selling against.

For a server you started yourself, LM Studio included, there is nothing to run:
put its address in the config as kind = "openai-compatible" and point endpoint
at its /v1.

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
------
    ai-trader setup        # once: takes your key, registers this machine
    ai-trader serve        # sells until you stop it

Or, if you unpacked this by hand and would rather not put anything on your
PATH, `./start.sh` does both.

Leave it running; Ctrl-C drains, finishing any job in flight before it exits.
There is no background mode yet, so on a machine you want selling unattended,
run it under systemd, launchd, tmux, or whatever you already use to keep a
process alive.

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

    http://127.0.0.1:5100

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
  - 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 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, or set it to 0 to turn it off.

KEEPING IT UP TO DATE
---------------------
Updates are required. On start the client checks the venue for a newer version,
and if this folder is behind it downloads the current client, unpacks it here,
and relaunches automatically. Everything under ~/.ai-trader - your key, config,
and node identity - is untouched, because it lives outside this folder. You do
not need to do anything. `ai-trader update` does it on demand.

BUYING FROM THE VENUE
---------------------
One account both sells and buys. To point an agent tool - Cursor, Aider, an
OpenAI SDK script, anything that speaks /v1/chat/completions - at the venue:

    ai-trader proxy --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;
run it alongside `serve` 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.

`ai-trader check` shows which catalog models this machine could serve itself,
free, instead of buying them.

TUNING
------
- Everything in the control panel is editable live; changes are saved to
  ~/.ai-trader/config.overrides.json and survive a restart.
- ~/.ai-trader/config.toml is the file version of the same settings (handle,
  region, models, floors, and the [schedule] and [affinity] blocks). The panel
  layers on top of it.
- 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.
