# SolTrench Python starters

These 15 small projects are starting points for the current SolTrench API.

Data, research, and read-only quote starters:

- `launch-collector.py` — append every new-token event to JSONL.
- `quote-monitor.py` — poll the read-only quote endpoint for one mint.
- `wallet-watcher.py` — print trades involving one wallet.
- `token-trade-tape.py` — print a compact live tape for one token.
- `launch-webhook-relay.py` — forward launches to your own adapter service.
- `live-ohlcv-generator.py` — aggregate one token's trades into raw-unit candles.
- `fresh-launch-screener.py` — print native-SOL launches matching a quote rule.
- `price-volume-alerts.py` — alert on relative movement and rolling raw volume.
- `local-strategy-runner.py` — save live-forward quote decisions to JSONL.

Unsigned-build and tracking starters:

- `trade-ticket-cli.py` — preview a trade and optionally save unsigned bytes.
- `scheduled-buyer.py` — preview at a UTC time and optionally save unsigned bytes.
- `transaction-watchdog.py` — persist tracking, landed, and final statuses.

Explicit live-funds starters:

- `launch-round-trip.py` — buy a launch, confirm, hold three seconds, then sell.
- `take-profit-stop-loss.py` — trigger a tracked full exit from relative ratios.
- `fast-entry-latency-lab.py` — measure one real fast-mode buy through confirmation.

Use Python 3.10 or newer. On macOS, Linux, or WSL, install the shared
dependencies with:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

On Windows PowerShell:

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -r requirements.txt
```

Every script reads credentials from environment variables. None contains an API
key. Live-funds examples load a Solana keypair from a local JSON file and send
only its public key to SolTrench.

Data-only starters require `SOLTRENCH_API_KEY`. Add the project-specific input,
then run the file. On macOS, Linux, or WSL:

```bash
export SOLTRENCH_API_KEY="<your-wallet-linked-api-key>"

python launch-collector.py
TOKEN_MINT="<mint>" python quote-monitor.py
TOKEN_MINT="<mint>" python token-trade-tape.py
WATCH_WALLET="<wallet>" python wallet-watcher.py
WEBHOOK_URL="https://your-adapter.example/launches" python launch-webhook-relay.py
TOKEN_MINT="<mint>" python live-ohlcv-generator.py
python fresh-launch-screener.py
TOKEN_MINT="<mint>" python price-volume-alerts.py
python local-strategy-runner.py
```

On Windows PowerShell, set each required variable on its own line before the
command. For example:

```powershell
$env:SOLTRENCH_API_KEY = "<your-wallet-linked-api-key>"
$env:TOKEN_MINT = "<mint>"
python .\quote-monitor.py
```

The webhook starter sends SolTrench's normalized event envelope to an endpoint
you control. That endpoint must translate it into the native Discord, Telegram,
or other destination schema.

## Preview and unsigned-build starters

`trade-ticket-cli.py` and `scheduled-buyer.py` require the public
`SOLANA_WALLET` linked to the API key. They preview by default. Setting
`BUILD_UNSIGNED=yes` creates an intent and saves unsigned transaction bytes;
neither script loads a keypair, signs, or broadcasts. Rebuild expired
transactions instead of submitting stale saved bytes.

```bash
SOLANA_WALLET="<wallet>" TOKEN_MINT="<mint>" AMOUNT_RAW="1000000" \
  python trade-ticket-cli.py

SOLANA_WALLET="<wallet>" TOKEN_MINT="<mint>" QUOTE_AMOUNT_RAW="1000000" \
  EXECUTE_AT="2026-07-30T12:00:00Z" python scheduled-buyer.py
```

PowerShell equivalent for the first preview:

```powershell
$env:SOLANA_WALLET = "<wallet>"
$env:TOKEN_MINT = "<mint>"
$env:AMOUNT_RAW = "1000000"
python .\trade-ticket-cli.py
```

The watchdog needs the real identity from one unsigned build and local signing
flow. Start it, wait until it prints `TRACKING ARMED`, and only then let the
separate caller broadcast through its own RPC.

```bash
INTENT_ID="<intent>" TRANSACTION_SIGNATURE="<signature>" \
  SOLANA_WALLET="<wallet>" TOKEN_MINT="<mint>" ACTION="buy" \
  python transaction-watchdog.py
```

## Live-funds starters

Live examples require `SOLANA_RPC_URL`, `SOLANA_KEYPAIR`, and the explicit
`ENABLE_LIVE_TRADING=yes` acknowledgement. The keypair must be the same wallet
linked to `SOLTRENCH_API_KEY`, or build and tracking requests will be rejected.

```bash
export SOLANA_RPC_URL="https://your-solana-rpc.example"
export SOLANA_KEYPAIR="/absolute/path/to/low-balance-keypair.json"
export ENABLE_LIVE_TRADING="yes"

python launch-round-trip.py

TOKEN_MINT="<mint>" ENTRY_QUOTE_AMOUNT_RAW="<entry-quote-raw>" \
  ENTRY_TOKEN_AMOUNT_RAW="<entry-token-raw>" python take-profit-stop-loss.py

TOKEN_MINT="<mint>" python fast-entry-latency-lab.py
```

On Windows PowerShell, the same acknowledgement and one latency-lab run are:

```powershell
$env:SOLANA_RPC_URL = "https://your-solana-rpc.example"
$env:SOLANA_KEYPAIR = "C:\absolute\path\to\low-balance-keypair.json"
$env:ENABLE_LIVE_TRADING = "yes"
$env:TOKEN_MINT = "<mint>"
python .\fast-entry-latency-lab.py
```

Review cost inputs before running live code. The round-trip defaults request a
`0.0001` SOL buy plus a `0.00001` SOL priority fee for each leg. The latency lab
defaults to one `0.0001` SOL buy with a `0.00001` SOL priority fee and does not
auto-sell. Solana base fees, token-account rent, and trading costs are
additional. The round-trip exposes `BUY_SOL`, `BUY_PRIORITY_FEE_SOL`, and
`SELL_PRIORITY_FEE_SOL`; the other live starters expose `PRIORITY_FEE_SOL`.

Use a dedicated low-balance wallet. Both the round-trip and take-profit /
stop-loss examples use a `"100%"` sell, which includes any pre-existing holding
of that token. The round-trip's three-second timer begins after the buy is
confirmed, not when it is requested.

The latency lab describes one caller, RPC, mint, network path, and moment. Its
result is not a benchmark cohort, SLA, or promise of future performance.

These examples are deliberately small foundations, not production strategies.
Add reconnect handling, persistence, position limits, balance checks, alerting,
and your own failure policy before running unattended.