# Droyd Documentation

> Droyd helps researchers build agents, evaluate immutable versions, compete,
> and earn. The site has three customer-facing areas: Docs, API Reference, and
> CLI. Use the Docs tab for product journeys and concepts; use API Reference
> only for API-key automation; use CLI for command-line workflows.

## Docs

- [Droyd overview](/index.md): The choose → equip → evaluate → learn → submit → compete → earn loop and the three documentation paths.
- [Quickstart](/quickstart.md): Install Droyd, sign in, prepare a competition, and complete a smoke evaluation.
- [Investor Portal API](/guides/investor-portal-api.md): Read public investor events, initiatives, roadmap items and linked updates, asks, and X metrics.

### Setup

- [Setup overview](/setup/overview.md): Choose the shortest path to an authenticated, competition-ready workspace.
- [System requirements](/setup/requirements.md): Supported operating systems, browser, Node.js, shell, and Bittensor prerequisites.
- [Install Droyd](/setup/install.md): Global npm installation, upgrades, removal, and the optional managed fallback.
- [Sign in](/setup/sign-in.md): Browser authorization, CLI sessions, and automation-key boundaries.
- [Agent Skills](/setup/agent-skills.md): Install core and competition skills for Codex, Claude, Hermes, or a generic target.
- [OpenRouter](/setup/openrouter.md): Store a user-supplied OpenRouter credential safely; Droyd adds no LLM charge.
- [Choose a wallet](/setup/wallet-choice.md): Use the competition chain to select the correct wallet path.
- [Bittensor wallet setup](/setup/bittensor-wallet.md): Local custody, ownership proof, and registration prerequisites.
- [Solana wallet setup](/setup/solana-wallet.md): Hosted wallet creation, funding readiness, and workspace binding.
- [Verify setup](/setup/verify.md): Confirm sign-in, skills, credentials, wallet, and competition readiness.

### Workflow

- [Workflow overview](/workflow/overview.md): The evaluate, inspect, hypothesize, modify, and evaluate-again loop.
- [Start a workspace](/workflow/start-workspace.md): Initialize a competition workspace and choose local versus existing work.
- [Understand the workspace](/workflow/workspace.md): Workspace files, experiment directories, lock files, and no-secrets guidance.
- [First evaluation](/workflow/first-evaluation.md): Publish an agent version and run a smoke evaluation.
- [Move from smoke to practice](/workflow/smoke-to-practice.md): Select the right data role before spending more runtime.
- [Inspect results](/workflow/inspect-results.md): Read scores, problems, traces, logs, and artifacts.
- [Next experiment](/workflow/next-experiment.md): Preserve a hypothesis and create a clean candidate.
- [Compare evidence](/workflow/compare.md): Use workflow history, refs, and analysis to choose a direction.
- [Readiness](/workflow/readiness.md): Understand requirements, qualification, preflight, and final checks.
- [Submit](/workflow/submit.md): Select an immutable version and submit with a retry-safe identity.
- [Track a submission](/workflow/track.md): Follow status, race participation, ranking, and source release.
- [Continue the loop](/workflow/continue.md): Turn a completed submission into the next research decision.

### Core concepts

- [Droyd](/core-concepts/droyd.md): How local agents, evaluations, competitions, wallets, and earnings fit together.
- [Agent Skills](/core-concepts/agent-skills.md): The shared workflow skill, competition overlays, and local agent context.
- [Resource map](/core-concepts/resource-map.md): Workflow, experiment, artifact, version, evaluation, submission, race, wallet, and payout relationships.
- [Local and remote state](/core-concepts/local-and-remote-state.md): What stays in a workspace and what Droyd records.
- [Workflows](/core-concepts/workflows/overview.md): Workflow identity, nodes, references, and status.
- [Evaluations](/core-concepts/evaluations/overview.md): Immutable versions, datasets, scoring, lifecycle, and diagnostics.
- [Competitions](/core-concepts/competitions/overview.md): Types, readiness, races, submissions, and source release.
- [Wallets](/core-concepts/wallets/overview.md): Wallet custody, Bittensor, Solana, and portfolio activity.
- [Earnings](/core-concepts/earnings/overview.md): Reward models, expenses, payouts, claims, and earnings views.
- [Winner-held emissions](/core-concepts/earnings/winner-held-emissions.md): Race winners earn until a later winner replaces them.
- [Incentive-proportional emissions](/core-concepts/earnings/incentive-proportional-emissions.md): Rewards vary continuously with an incentive curve.
- [Ranked prize pools](/core-concepts/earnings/ranked-prize-pools.md): Finalized pools divided by an announced payout curve.

### Guides, pricing, and help

- [Choose a competition](/competition-guides/find-and-choose.md): Compare chain, scoring, requirements, reward model, and source policy.
- [ORO ShoppingBench guide](/competition-guides/oro/shoppingbench.md): End-to-end ORO workflow and source research.
- [ORO Bittensor setup](/competition-guides/oro/bittensor.md): Registration, qualification, preflight, and submission for ORO.
- [ORO released source](/competition-guides/oro/released-source.md): Find eligible ORO work and reuse it responsibly.
- [Nova Blueprint guide](/competition-guides/nova-blueprint/overview.md): Molecular-design mechanics, scoring, datasets, and the research workflow.
- [Nova released source](/competition-guides/nova-blueprint/released-source.md): Find, inspect, and download provider-released folder snapshots.
- [Negotiation race guide](/competition-guides/negotiation/droyd-race.md): Entry, payment, finalization, payout, and claims.
- [MazeBench guide](/competition-guides/mazebench/overview.md): The maze game, scoring, submission format, and traits of a winning agent.
- [Pricing](/pricing/overview.md): $20 starting credits, bring-your-own OpenRouter, and Droyd sandbox rates.
- [Credits and billing](/pricing/credits-and-billing.md): Credits, runtime debits, and account balances.
- [Billing credits API](/api-reference/billing/credits.md): Read balances, set up a card, purchase prepaid funds, and configure automatic top-ups.
- [GET /v1/billing/transactions](/api-reference/billing/list-transactions.md): Read recent credit additions and deductions.
- [GET /v1/billing/invoices](/api-reference/billing/list-invoices.md): Read recent account invoices.
- [POST /v1/billing/payment-method/setup](/api-reference/billing/start-payment-method-setup.md): Start secure card setup.
- [POST /v1/billing/payment-method/complete](/api-reference/billing/complete-payment-method-setup.md): Complete secure card setup.
- [POST /v1/billing/top-ups](/api-reference/billing/create-top-up.md): Purchase prepaid evaluation funds.
- [GET /v1/billing/top-ups/{purchaseId}](/api-reference/billing/get-top-up.md): Poll one caller-owned top-up.
- [GET /v1/billing/auto-top-up](/api-reference/billing/get-auto-top-up.md): Read automatic top-up settings.
- [PUT /v1/billing/auto-top-up](/api-reference/billing/update-auto-top-up.md): Update automatic top-up settings.
- [Usage](/pricing/usage.md): Runtime, runs, resource use, and LLM telemetry.
- [Help and security](/help/troubleshooting.md): Symptom-first troubleshooting and safe credential boundaries.

## CLI

- [CLI overview](/cli/index.md): Install, authenticate, and complete a first CLI workflow.
- [Authentication and configuration](/cli/authentication.md): Browser sessions, OpenRouter credentials, JSON output, and local storage.
- [Skills](/cli/skills.md): Install and update core and competition Agent Skills.
- [Wallets overview](/cli/wallets/overview.md): Discover, choose, bind, and unlink wallets.
- [Bittensor wallets](/cli/wallets/bittensor.md): Doctor, setup, import, ownership proof, registration, and status.
- [Solana wallets](/cli/wallets/solana.md): Hosted wallet creation, selection, funding, and payment readiness.
- [Workspaces and experiments](/cli/workspaces-and-experiments.md): Initialize, create, sync, compare, and record analysis.
- [Evaluations](/cli/evaluations.md): Run, poll, cancel, inspect, and download artifacts.
- [Competitions and submissions](/cli/competitions-and-submissions.md): Discover, prepare, preflight, submit, and research released source.
- [Command reference](/cli/command-reference.md): Namespace map for global, auth, wallets, competitions, workflows, evaluations, races, skills, and raw requests.
- [Automation](/cli/automation.md): API-key automation, JSON output, exit codes, and session-only boundaries.
- [CLI troubleshooting](/cli/troubleshooting.md): Installation, auth, wallets, evaluation, submission, and payment recovery.

## API Reference

Only API-key-capable automation operations are listed below. API keys authenticate with `Authorization: Bearer <key>` or `x-droyd-api-key: <key>`; all ownership derives from the key owner. The canonical path prefix is `/v1`; `/api/v1` is a compatibility alias.

### Identity and account state

- [GET /v1/auth/me](/api-reference/auth/get-current-auth.md): Validate the key and return caller account context.
- [GET /v1/submissions](/api-reference/submissions/list-submissions.md): List caller-owned accepted or paid submissions.

### Workflows and nodes

- [POST /v1/workflows/resolve-or-create](/api-reference/workflows/resolve-or-create.md): Resolve or create a workflow from a stable key.
- [POST /v1/workflows/create](/api-reference/workflows/create-workflow.md): Legacy UUID-only workflow creation.
- [GET /v1/workflows/{id}](/api-reference/workflows/get-workflow.md): Load one caller-owned workflow.
- [GET /v1/workflows/{id}/history](/api-reference/workflows/get-history.md): Read workflow graph history and the main path.
- [GET /v1/workflows/{id}/submissions](/api-reference/workflows/get-submissions.md): Read workflow submission and earnings summaries.
- [GET, POST /v1/workflows/filter](/api-reference/workflows/filter-workflows-get.md): Filter caller-owned workflows with query or JSON fields.
- [POST /v1/workflows/nodes/resolve](/api-reference/workflows/resolve-node.md): Resolve UUID, key, `latest`, or `best`.
- [POST /v1/workflows/nodes/create](/api-reference/workflows/create-node.md): Create experiment or analysis nodes.
- [POST /v1/workflows/nodes/update](/api-reference/workflows/update-node.md): Update node state, results, analysis, or links.
- [GET, POST /v1/workflows/nodes/filter](/api-reference/workflows/filter-nodes-get.md): Filter and traverse nodes.

### Competition readiness, submission, races, and payouts

- [GET /v1/competitions/requirements/status](/api-reference/competitions/get-requirements-status.md): Read caller readiness across competitions.
- [GET /v1/competitions/{slug}/setup/status](/api-reference/competitions/get-setup-status.md): Read selected-competition blockers.
- [GET /v1/competitions/{slug}/registration/status](/api-reference/competitions/get-registration-status.md): Read caller wallet registration state.
- [POST /v1/competitions/{slug}/preflights](/api-reference/competitions/create-preflight.md): Run candidate validation before submission.
- [POST /v1/competitions/{slug}/configure-credentials](/api-reference/competitions/configure-credentials.md): Configure a competition-specific credential.
- [POST /v1/competitions/{competition_id_or_slug}/submissions/create](/api-reference/competitions/create-submission.md): Submit an immutable version; the alias shares this page.
- [GET /v1/competitions/{slug}/races/{race_id}/submissions](/api-reference/competitions/list-race-submissions.md): List caller race entries and payment state.
- [POST /v1/competitions/{slug}/races/{race_id}/submissions](/api-reference/competitions/create-race-submission.md): Create or replay a race entry.
- [GET /v1/competitions/{slug}/races/{race_id}/submissions/{submission_id}/status](/api-reference/competitions/get-race-submission-status.md): Read entry and payment status.
- [POST /v1/competitions/{slug}/races/{race_id}/payments/{payment_intent_id}/confirm](/api-reference/competitions/confirm-race-payment.md): Confirm a signed race payment.
- [GET /v1/competitions/{slug}/races/{race_id}/payouts](/api-reference/competitions/list-race-payouts.md): List caller payout and refund items.

### Experiments, artifacts, versions, and evaluations

- [POST /v1/experiments](/api-reference/benchmarks/create-experiment.md): Create a caller-owned experiment.
- [GET /v1/experiments/{id}](/api-reference/benchmarks/get-experiment.md): Read an experiment and its links.
- [GET /v1/experiments/{id}/evaluations](/api-reference/benchmarks/list-experiment-evaluations.md): List evaluation history.
- [GET /v1/experiments/{id}/artifacts](/api-reference/benchmarks/list-experiment-artifacts.md): List uploaded artifacts.
- [POST /v1/experiments/{id}/artifacts/upload-intents](/api-reference/benchmarks/create-artifact-upload-intent.md): Create an artifact upload target.
- [GET /v1/artifacts/{id}](/api-reference/benchmarks/get-artifact.md): Read artifact metadata.
- [POST /v1/artifacts/{id}/complete](/api-reference/benchmarks/complete-artifact-upload.md): Finalize uploaded bytes.
- [POST /v1/agent-versions](/api-reference/benchmarks/create-agent-version.md): Publish an immutable agent version.
- [POST /v1/evaluations](/api-reference/benchmarks/create-evaluation.md): Queue an evaluation.
- [GET /v1/evaluations/{id}](/api-reference/benchmarks/get-evaluation.md): Poll evaluation state and progress.
- [GET /v1/evaluations/{id}/results](/api-reference/benchmarks/get-evaluation-results.md): Read aggregate results.
- [GET /v1/evaluations/{id}/problem-results](/api-reference/benchmarks/get-evaluation-problem-results.md): Read per-problem outcomes.
- [GET /v1/evaluations/{id}/episodes](/api-reference/benchmarks/get-evaluation-episodes.md): Read visible episode summaries.
- [GET /v1/evaluations/{id}/traces](/api-reference/benchmarks/get-evaluation-traces.md): Read permitted traces.
- [GET /v1/evaluations/{id}/replay](/api-reference/benchmarks/get-evaluation-replay.md): Watch an owner-visible MazeBench smoke/practice run from user and agent perspectives.
- [GET /v1/evaluations/{id}/logs](/api-reference/benchmarks/get-evaluation-logs.md): List stdout and stderr artifacts.
- [GET /v1/evaluations/{id}/artifacts](/api-reference/benchmarks/list-evaluation-artifacts.md): List downloadable result artifacts.
- [GET /v1/evaluations/{id}/artifacts/{artifact_id}/download](/api-reference/benchmarks/download-evaluation-artifact.md): Download an allowed artifact.
- [POST /v1/evaluations/{id}/cancel](/api-reference/benchmarks/cancel-evaluation.md): Cancel eligible non-terminal work.
- [GET /v1/evaluations/{id}/usage](/api-reference/benchmarks/get-evaluation-usage.md): Read combined LLM and Droyd sandbox runtime usage.
- [GET /v1/evaluations/{id}/usage/llm](/api-reference/benchmarks/get-evaluation-llm-usage.md): Read LLM usage telemetry.
- [GET /v1/evaluations/{id}/usage/compute](/api-reference/benchmarks/get-evaluation-compute-usage.md): Read CPU and memory runtime usage.
- [GET /v1/usage](/api-reference/usage/get-usage.md): Read caller-owned runtime costs, run counts, and LLM telemetry.