account_usage | Your metered usage ledger: placements, destroys, estimated hours and USD,
and the platform fee (2.5%, $0.01 min, $5.00 cap per lease per UTC day) priced
at the rate live at event time. Distinct from fee_bps, the display markup. |
best_value | Perf-per-dollar board: for each GPU model, best live price vs its FP16
tensor throughput (dense, vendor spec sheets) -> TFLOPS per dollar-hour.
The answer to 'most compute for my budget' rather than 'cheapest card'.
Models without a defensible public spec figure are listed as unrated. |
cancel_limit_order | Cancel a limit order. Requires the order_secret from create_limit_order. |
create_limit_order | Place a standing LIMIT ORDER: when the best live fee-adjusted price for
gpu (and optional offer_class) trades at or under max_price_per_gpu_hr,
the station cuts a signed FILL TICKET naming the exact offer. The station
never holds your provider key — the ticket is executed by whoever does:
the open-source keyholder sidecar (/agents/#sidecar), your own agent
long-polling POST /api/orders/{id}/ticket, or a human with curl. Returns
the order with order_secret SHOWN ONCE — it authenticates ticket reads and
the fill call for this order only and can rent nothing by itself. Triggers
are checked on the poll cadence (~5-min bars, not tick-by-tick); orders
expire in 30 days; a ticket lasts ~4 minutes then the order re-arms.
standing=true makes it a STANDING order — compute that survives: after a
live fill the sidecar keeps watching the machine, and when it is preempted
or dies the order re-arms and refills from the CURRENT best offer, up to
max_refills times with cooloff_seconds between death and refill. Honest
limits: this re-provisions the MACHINE, not the WORK (GPU memory is not
portable — resume from your own checkpoints); refills need your sidecar
alive (it is both witness and executor); cancelling stops supervision but
cannot destroy a running machine (the station holds no key). Watchdog:
spend_alert_usd / age_alert_hours fire a "still yours?" webhook once per
machine when the spend ESTIMATE (uptime x price; the provider's bill is
authoritative) or age crosses your line — auto_destroy_budget_usd remains
the hard stop. |
create_watch | Create a price watch (tripwire): fires when the best live fee-adjusted
price per GPU-hour matching gpu (and optional offer_class) drops to or
under max_price_per_gpu_hr. Checked every poll (~5 min). Returns the watch
with its id — the id is the only key; poll it with watch_status, or give a
public webhook_url to be POSTed on each trip. Watches re-arm when the
price climbs 2% back over the line. |
delete_watch | Delete a watch by id. |
destroy_rental | Destroy an instance previously placed on your account (vast or runpod).
Your key passes through and is never stored. |
fill_limit_order | Execute a limit order's live fill ticket on YOUR provider key (used for
this one call, never stored). Only works while the order is ticketed; the
offer is re-quoted live and refused above the order's line. Idempotent per
order — a retry returns the first receipt rather than renting a second
machine. The order's auto_destroy_budget_usd (if set) arms the budget
guard exactly as rent_offer does. |
get_offer | Fetch one offer by its id (from search_offers). |
idle_history | The idle-capacity index over time: share of listed GPU capacity that is
interruptible (spot/bid) — idle hardware looking for work. Points are
[ts, idle_share, idle_offers, total_offers]. |
limit_order_status | State of a limit order (armed/ticketed/filled/cancelled/expired), last
price seen, recent events. Pass order_secret to also read the live fill
ticket when one is cut. |
market_stats | Live market snapshot: total offers, GPU models, idle-capacity share,
per-provider freshness/health, cheapest price per model, current fee_bps. |
price_history | Price history for one GPU model (exact name from search_offers/market_stats,
e.g. 'RTX 4090'). offer_class: on_demand | interruptible. Returns per-provider
series of [ts, min_price_per_gpu_hr, median_price_per_gpu_hr, offer_count];
ranges past 3 days are bucketed (hourly, then 6-hourly past a week). |
price_position | Rent-now-or-wait context: where the current best price for one GPU
model sits inside its own trailing 7/30-day range (percentile, 24h trend,
verdict). Descriptive, not a forecast. |
provider_reliability | How dependable each provider's data feed has been for this station
(poll success over the trailing window), plus the provider's own average
machine reliability where reported. feed_score is about the DATA, not
their hardware. |
register_account | Create a metering account: returns a bearer token (shown once, we keep
only a hash). Pass it as account_token on rent calls to build a usage
ledger you can read back with account_usage. Optional — renting works
without one. |
rental_status | Live state of an instance on your account: running/starting/stopped/
gone, uptime, price, estimated spend so far, and the budget guard's state
if one is armed. Read-only; your key passes through and is never stored. |
rent_best | One-shot rent: search the live book with these filters and place on the
best (cheapest) matching offer — 'cheapest H100 under $2/hr, go'. Same
guarantees as rent_offer (dry-run default, live re-quote, your
max_price_per_gpu_hr is absolute). If the best offer is already gone it
walks to the next, at most 3, and reports what it skipped. |
rent_offer | Place a rental on YOUR provider account (BYO key — it is used for this
one call and never stored). Default is a DRY RUN returning exactly what
would be executed; a live placement needs dry_run=false AND confirm=true.
The offer is re-quoted live first and refused if its price exceeds
max_price_per_gpu_hr. Executes on vast and runpod offers. Pass an
idempotency_key so retries return the first receipt instead of renting
twice. auto_destroy_budget_usd arms the budget guard: this station then
holds your key in PROCESS MEMORY ONLY and destroys the rental when
estimated spend reaches the cap (a station restart drops the guard — the
receipt says so; poll rental_status as backstop). account_token (from
register_account) attributes the rental to your usage ledger. |
rent_x402 | Rent a prepaid block of GPU time with a wallet and NO account, NO API key
and no human, over x402 (HTTP 402 micropayments, USDC on Base).
Call it with no arguments and you get the payment challenge: an x402
PaymentRequirementsResponse whose accepts[0].extra.x402_fee states the block
price, the platform fee IN DOLLARS, that there are no refunds, and that you
are charged only after the lease is live. Sign the EIP-3009
transferWithAuthorization it describes, then call again with x_payment set to
the base64 PaymentPayload (the same value the HTTP rail sends as X-PAYMENT).
`ssh_pubkey` is HOW YOU GET IN, and is required on the paying call: pass the
public half of your ssh key (one line, the contents of id_ed25519.pub). It is
written into the rented container's authorized_keys and nowhere else, and the
receipt comes back with the host and port to connect to. A block nobody can
enter is not sold.
`lease_id` is minted by the challenge — send back the one you were given; it
is the accrual key for the daily fee cap and this station refuses ids it did
not mint or that belong to another payer.
`originator` is an OPTIONAL opaque attribution label (<=64 chars, e.g. a
handle or a reverse-DNS name) naming the client implementation that produced
the fill. It is carried unmodified onto the receipt and onto the public
ledger row, and it never affects the price, the fee, verification or
settlement — the same block costs the same either way.
Returns the receipt on success. Every fill is published at /api/receipts.
Wire contract: docs/X402-FEE-0.1.md, frozen as x402-fee/0.1.
Note for x402 MCP-transport clients: this tool takes the payment as an
ARGUMENT rather than in _meta["x402/payment"]. The payload is byte-identical;
only the channel differs, because a tool argument is the one place every MCP
client can portably put it. The HTTP rail is fully transport-conformant. |
search_offers | Search live GPU offers. gpu matches the model name (e.g. '4090', 'H100').
offer_class: on_demand | interruptible | reserved. country: ISO-2 (e.g. US),
a comma list ('DE,NL'), or 'EU' for the 27 member states. min_gpu_count
filters to multi-GPU configs (8 = full 8x nodes). region substring-matches
the provider's region/datacenter label. Returns offers ranked
cheapest-first by price_per_gpu_hr. |
spot_spread | On-demand vs interruptible spread: the live discount for idle capacity
per model; pass gpu_model for its history too. |
true_cost_notes | The billing fine print behind the $/hr, verified per provider from
their own published pages (source URL + date on every claim): billing
granularity (per-second vs per-minute), whether storage bills while
stopped, bandwidth/egress fees, and the commonly-missed gotchas (e.g.
Vast bandwidth never appears in $/hr; RunPod stopped volume disk costs
double). Providers we have not verified are listed with NO claims. |
watch_status | Current state of a watch: armed/tripped, last price seen, recent
events, and the best matching offer right now. |
will_it_fit | Will this model fit, and what does a fitting machine cost right now?
Deterministic VRAM arithmetic — weights (params x bytes/precision) + KV
cache (2 x layers x kv_heads x head_dim x context x batch) + stated
overhead — checked against the live book, cheapest fitting offers first.
Pass a known model slug (llama-3.1-8b/70b/405b, mistral-7b, mixtral-8x7b,
qwen2.5-7b/32b/72b, gemma-2-9b/27b) OR params_b for a stated Llama-like
guess. precision: fp16/int8/int4. If you pass tokens_per_s (YOUR measured
throughput — we never invent one), each offer gains usd_per_m_tokens.
Every approximation is in the assumptions list, not fine print. |