Documentation: 0.5.0 (source: v0.5.0).
# Mining

> Resource deposits, active extraction, and reading a rate rather than a total.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/mining/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

Mining is a fleet sitting at an asteroid, extracting a resource over time. Two
things are worth reading: what a deposit holds, and what a fleet is currently
pulling out of it.

:::game[Mining is production over time]
Mining does not give a fleet a pile of resources instantly. The fleet stays at
an asteroid and slowly extracts material into its cargo hold. A better mining
fleet gathers resources faster, but it still needs time to do the work. The
operation also has to stop when the fleet leaves or runs out of room.
:::

## Is this fleet mining?

```ts
const mining = await fleet.mining.get();

if (mining === undefined) {
  // Not mining. This is a normal state, not an error.
}
```

`undefined` is the answer for a fleet that is docked, in transit, or idle. The
SDK returns it rather than throwing, because "not mining" is an ordinary fact
about a fleet rather than a failure to read one.

> **Runnable example — Read mining state and a deposit.** A fleet mining state - undefined is a normal answer - and a resource deposit. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/mining/.

## Rates, not totals

The important mental shift: mining gives you a **rate and a start**, not a
running total. Nothing on chain increments a counter as ore accumulates.

What you get is enough to compute the amount yourself: when extraction started,
the rate it runs at, and what resource is coming out. The amount at any moment
is derived from those plus the current time.

That is why a mining read has a timestamp that matters, and why caching it for
a long time is misleading in a way that caching a fleet's name is not.

:::game[The best asteroid depends on the job]
Asteroids do not all contain the same materials, and some deposits are richer
than others. A rich deposit lets a fleet pull out more material in the same
amount of time, but the fleet's own mining ability still matters. The richest
asteroid is not always the best choice if it is far away, dangerous, or costly
to reach. Players balance the resource they need against yield, travel, and
risk.
:::

## Deposits

A resource deposit is the asteroid's side of the same relationship:

```ts
const deposit = await getResourceDeposit(ctx, depositAddress);
```

It describes what the asteroid holds and the properties that govern extraction
from it.

## Gotchas

**Rates depend on the fleet, not just the asteroid.** What a fleet extracts per
unit time is a function of its ships and the resource's properties together.
Two fleets at the same asteroid do not mine at the same speed.

**Derived amounts are computed, not stored.** If you display an accumulating
total, you are computing it. Recompute it on a timer rather than reading it
once and treating it as current.

**A deposit can be read without a fleet.** Deposits and fleet-mining state are
separate reads. You do not need one to get the other.

## Reference

- [`mining`](/reference/mining/) — every export in this entry
- [`cargo`](/guides/cargo/) — where extracted resources end up
- [`world`](/guides/world/) — finding asteroids in a system