Guide

Coding agents search the web through a Twilight Slot; every verified search earns a share of the epoch's reward. Install the miner, connect your agents, get paid on devnet. This page is the whole workflow; the Reference has every command, file, field and endpoint.

Twilight search mining

Twilight pays people for the work their coding agents already do. Every web search an agent runs through a Twilight Slot is verified by that Slot's authorization server and counted toward a per-epoch reward on the Twilight chain. No GPU, no daemon, no staking: the proof of work is a verified search, and the miner is a small binary your agent calls the way it calls any shell tool.

The first Slot is the search router: one API that fans a query out across nine web indexes at once, ranks the candidates, and returns all of them with the winner marked. Agents get better search than any single index gives; the router gets the trajectories it learns to route from; the person running the agent gets paid. This site documents the participant side end to end and the router's API.

How it works

Six things happen around one search. Only the first and last involve you.

1. Your agent searches. It runs dropin-miner search "<query>" because the installed skill tells it to. The command sends the query to the router with your sr- API key and a small trace: hashed session ids and the assistant text that led to the search.
2. The router fans out. Slot 3 sends the query to every index in its default set, scores the answers (citations, agreement between indexes, recency), ranks them, and returns all candidates with one chosen. It stores the request as a trace and writes a metadata-only verification row for the authorization server: which key searched, when, what it cost. Never the query text.
3. The miner records it. search writes an intake record on disk and starts a short, detached flush. Nothing runs between searches.
4. The flush talks to the AS. It joins the target epoch if you are not in it yet, promotes intake records into observations, and submits them. The AS answers with a signed receipt per epoch.
5. The AS verifies. It matches your observations against the router's verification rows. A match is a verified observation. One per epoch makes you a candidate for that epoch's draw.
6. The epoch settles. When the epoch closes, the AS runs the draw over the candidate set and pays the pot to the eligible participants' declared payout addresses on the chain.

Quickstart

Ten minutes, one terminal. You need an account on https://platform.nyks.dev (it issues the API key and the enrollment token) and a machine that runs at least one of the supported coding agents.

Install

curl -fsSL https://raw.githubusercontent.com/twilight-project/dropin-miner/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/twilight-project/dropin-miner/main/scripts/install.ps1 | iex

npx dropin-miner version        # the npm wrapper downloads the same checksummed release

The installer fetches the release for your platform (macOS and Linux on x86-64 and arm64, Windows on both), verifies its checksum, puts the binary at ~/.tokendrop/bin/dropin-miner, and hands off to setup, which asks its questions in order:

First search

dropin-miner search -format model "what is proof of authority consensus"
dropin-miner flush
dropin-miner doctor

  authorization server  OK       https://minis.nyks.dev — slot 3 on twilight-devnet-3
  enrolled              OK       the AS accepted this installation's authorization
  joined this epoch     OK       epoch 180 — accepted
  payout address        OK       twilight1… is in force
  earning               OK       epoch 180 — 1 observation verified, which qualifies

Then restart any coding agent that is already open and search as usual. Your first reward takes an hour or two: you join an epoch two ahead, and it has to close and settle.

Your coding agents

dropin-miner agents install detects the agents on your PATH and gives each a web-search skill that runs through the router, plus the hooks the host supports. Every config edit is a JSON merge that adds our entries and nothing else; uninstall removes exactly those.

On and off

Out of the box the skill tells your agent to prefer this search over its built-in one. If you would rather your agent use its own search unless you ask for this one, say so once, from inside the agent or from a shell:

/dropin-miner off        # in Claude Code, Codex or Cursor
/dropin-miner on
/dropin-miner status

dropin-miner agents prefer off|on|status

The choice is recorded beside your config and the installed skills are rewritten from it, so it holds in every agent, from its next start, and across reinstalls. While it is off, naming dropin-miner or the router in a request still routes that one search here. Searches that do not come here earn nothing.

dropin-miner agents status
dropin-miner agents uninstall

Searching

The exact command the skill teaches, with the config path filled in at install:

"/…/.tokendrop/bin/dropin-miner" search -config "/…/.tokendrop/tokendrop.toml" -format model "<query>"

-format model prints one block per index, the chosen one first: an answer when an index gave one, then numbered results with URL, title and snippet. -format json prints the router's full response. -tier fast asks for the cheap tier; leave it off for the balanced default.

search 01a07aa6-…  8 candidates

[you] (chosen) retrieval
  1. https://apla.readthedocs.io/…/consensus.html — Proof-of-Authority consensus
     This section describes Proof-of-Authority consensus and its implementation…
  2. https://ethereum.org/developers/docs/consensus-mechanisms/poa — Proof-of-authority (PoA)
     …

[exa] retrieval
  1. https://ethereum.org/developers/docs/consensus-mechanisms/poa — Proof-of-authority (PoA)
  …

What a search fans out to

The default set on devnet is nine indexes behind eight arms, all reached through one upstream aggregator so the Slot pays one bill at pass-through rates: Exa, Tavily, Linkup, Brave, You.com, Parallel, SerpAPI (Google), and a pinned pair the Slot has no other adapter for, Ceramic and Seltz. SerpAPI rides the slow lane: it is dispatched with every search but not waited for, and its results land on the stored trace afterwards, so the response is bounded by the fast arms at roughly three seconds.

The response carries the router's reasoning, not just results: a per-index referee score (citations, distinct domains, dead links, recency), a consensus block (how many domains the indexes agreed on), the ranking, and a decision block recording which set was chosen and why. See the Reference for every field.

Your API key

A search takes its key from TOKENDROP_API_KEY if set, else from the file login wrote, else from OPENAI_API_KEY. login reads the key from the terminal (never an argument), verifies it with a zero-spend probe, and writes ~/.tokendrop/credentials.json owner-only; it is refused if it is a symlink or readable by others.

dropin-miner login            # paste the key; echo is off
dropin-miner login -show      # where a search would get its key, masked
dropin-miner login -forget

Epochs, eligibility, and getting paid

The Slot's authorization server divides time into epochs of about 32 minutes. Each epoch has a target you join in advance, a window in which observations are accepted and verified, and a settlement in which the pot is distributed.

dropin-miner doctor reports setup — connected, enrolled, joined, paid, earning — and names the one thing to do when a check is not OK. What the chain has actually paid is a chain question: earnings reads the chain directly and counts only transfers from the rewards escrow account as mining payments, in utwlt (one TWLT is a million utwlt).

dropin-miner earnings            # -limit 0 for everything; totals are a floor if the walk truncates

Slots and the token supply

A Slot is Twilight's unit of proof of work. The chain does not verify work itself; it registers a bounded set of Slots, each run by an operator who provides a workload and an authorization server that verifies participation in it, and pays each active Slot a share of every block's emission. The Slot's authorization server then distributes its share to the participants who did the verified work. The search router is Slot 3.

How a Slot is registered

Slots are registered on chain by the network authority, not by self-service: MsgRegisterCoreSlot and MsgActivateCoreSlot are authority transactions, allow_self_registration is off on devnet, and the active set is capped at max_active_slots of 100 with a minimum of 1. The authority also removes, rotates keys and changes parameters; a separate emergency authority can only suspend. A Slot record carries its operator address, a consensus key (a Slot is also a validator, with one unit of voting power on devnet), a payout address, a settlement address the Slot pays participants from, a reward weight, and a selection policy. Operators update their own payout address and metadata and may inactivate themselves as long as the minimum stays met. Activation, key rotation and removal are height-delayed, and a consensus key cannot be reused for 100,000 blocks after removal.

Where the tokens come from

Emission is the chain's, not the Slot's. Every block mints a subsidy, summed over the epoch and clipped by the supply cap; the amount depends on the block count and the halving tier, never on how many Slots exist. At the epoch's close the pool is allocated among Slots by the blocks each was active for (DISTRIBUTION_METHOD_UNIFORM_ACTIVE_BLOCKS), floor-division dust carries forward, and each Slot's share is recorded as an entitlement held in the rewards module account. There is no claim transaction: the Slot's authorization server releases the entitlement by submitting settlement chunks on chain that pay participants directly, within the settlement window, and any remainder goes to the Slot's payout address. What a participant receives is therefore a share of a share: the Slot's fraction of the epoch's emission, divided among the participants eligible in that epoch.

Halving is by supply crossed, not by height. The per-block subsidy is initial_block_subsidy / 2^tier, where each tier begins when cumulative emission crosses max_supply − max_supply / 2^n:

How a Slot's share reaches participants

The chain records one distribution mode per era. On devnet it is TRUSTED_AS_DISTRIBUTION, valid from epoch 1: the Slot's authorization server computes the split and pays it, and the chain trusts that computation. In this mode the split is equal among everyone eligible, eligibility is one verified search in the epoch, and the on-chain selection machinery is not applied.

That machinery is already in the genesis for a later mode: a verifiable per-epoch selection over the candidate set, with a beacon drawn from block proposers 48 blocks after the epoch's close over a 24-block window that must include 12 externally proposed blocks from at least 3 distinct proposers, capped at 25% of candidates and 64 selected from at most 1,024. Each Slot also carries its own selection policy, 25% and 10 on devnet. When the chain switches a Slot to a selection mode, eligibility stops meaning payment and starts meaning a ticket in that draw. The docs will say so when it happens; do not plan on it now.

Wallet and payout address

Setup offers two ways to be paid. Either is a one-time payout declaration to the Slot.

dropin-miner payout show      # ACTIVE, and the address as the chain renders it
dropin-miner wallet address
dropin-miner wallet balance
dropin-miner wallet send <to> <amount>   # asks for the passphrase; type yes to confirm

What travels with a search, and how to turn it off

Each search carries a small trace beside the query so the router can group one task's searches: hashed session and turn identifiers (your agent's real ids never leave the machine), a call counter, a context-window generation, and the assistant text just before the search, capped at 32 KB. That text is conversation content leaving your machine; it goes only inside the search request, to the router, and the miner stores none of it beyond a per-workspace lineage file under ~/.tokendrop/sessions that the hooks maintain.

export TOKENDROP_TRACE=off      # send no trace at all; searches earn exactly the same

• The query itself rides in the command's arguments, so it is visible in ps and your shell history on your own machine. It is not a credential.
• The API key never goes on a command line, into an agent's config, or into the trace. It lives in the environment or the owner-only credentials file.
• The assistant text is sent as it is today. Redaction of secret shapes (API keys, bearer tokens, private keys) before it leaves the machine is in review and will ship in the next client release.
• Turning the trace off stops the wire; the hooks still maintain the on-disk lineage file under ~/.tokendrop/sessions, which never leaves the machine.
• If the router ever rejects a trace, the search is retried once without it. A trace never costs a search.
• The router keeps traces for 30 days by default; a tenant on zero-retention keeps no response content.

Identity and keys

Three credentials, three jobs. None of them is ever the same thing as another.

Enrollment by default is a device flow: a person approves in a browser. enroll -assertion redeems an enrollment token from stdin and needs no browser, which is what setup uses.

Removing it, and coming back

dropin-miner agents uninstall     # the skills, hooks and plugin, nothing else
rm ~/.tokendrop/bin/dropin-miner  # the binary

Nothing shipped here deletes ~/.tokendrop: it holds your wallet, your enrollment and your stored key, and the wallet is the only copy unless you kept the 24 words. Leave it, or set it aside as ~/.tokendrop.bak-<date>. The next setup finds either one, says what it holds, and offers to carry the wallet, enrollment, key and any unsent spool over, so you are not enrolled twice or paid to a second address.

Devnet status and known limitations

• Devnet tokens only. twilight-devnet-3, Slot 3. Parameters may change between epochs; the epoch length and split are the devnet's.
• Payout binding is declared, not proven. The AS trusts your declaration; a wallet-signature binding is specified but not enforced yet.
• Trajectory text is often missing from the trace on Claude Code (see Privacy). The ids are always there.
• Codex needs a sandbox network exception for the search command. Cursor hooks were verified against Cursor's documentation, not yet at scale.
• Windows stores the key and wallet behind an owner-only directory ACL rather than file modes, and has no interactive setup: the installer prints the enroll, wallet, join, agents and login steps for you to run by hand, and there is no previous-installation adoption yet.
• Hooks are fail-open. Any hook error produces nothing and exits 0, so mining can never block or break an agent's tool call. The flip side is that a broken hook fails silently; dropin-miner doctor and agents status are how you notice.
• Free tier is the fast lane. Research-grade arms stay paid; zero-retention is a paid-tier feature. The pricing page will say what.
• Mainnet timing is not promised here.

Troubleshooting

Glossary