> For the complete documentation index, see [llms.txt](https://docs.spacecoin.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spacecoin.org/spacerouter-proxy/proxy-provider-guide/claim-your-earnings.md).

# Claim Your Earnings

### How payment works

Every proxy request you serve produces a **receipt** — a tiny signed message that says "this many bytes were served at this price." The lifecycle is:

```
  ┌──────────────┐    you serve     ┌──────────────┐
  │   pending    │ ───────────────▶│  claimable   │
  │   _sign      │  gateway signs  │              │
  └──────────────┘                 └──────┬───────┘
        │                                  │ you submit
        │ sign error                       │ claimBatch()
        ▼                                  ▼
  ┌──────────────┐                  ┌──────────────┐
  │   failed     │                  │   claimed    │
  │  _retryable  │ ◀── claim error  │ (paid)       │
  └──────┬───────┘                  └──────────────┘
         │ second failure
         ▼
  ┌──────────────┐
  │   failed     │
  │  _terminal   │
  └──────────────┘
```

Three things you settle on chain:

1. The Provider app calls the on-chain `claimBatch()` function with your signed receipts.
2. The contract verifies each receipt against the network's signed approval and your wallet registration.
3. The SPACE for the entire batch is transferred to your **collection wallet** in a single transaction.

### Before your first claim

{% hint style="warning" %}
**Fund your Identity wallet with CTC**

Claims are broadcast from your **Identity** wallet (not your staking wallet). The Identity wallet pays the gas. Send **\~1 CTC** to it before clicking *Claim All Outstanding*. The Earnings screen shows the address with a copy button. Without CTC there, the claim transaction fails with `insufficient funds for gas`.
{% endhint %}

How much CTC is "enough"? Each claim transaction costs roughly 0.001–0.005 CTC depending on batch size. **1 CTC** is usually enough for hundreds of claim batches.

### Manual claim

#### From the GUI

1. Open **Earnings** from the status screen.
2. Confirm the Claim wallet card shows enough CTC.
3. Click **Claim All Outstanding**.
4. Wait — the button shows a progress indicator. The on-chain transaction usually confirms within \~15 seconds.
5. The claimed receipts move from **Claimable** to **History**. SPACE arrives in your collection wallet.

#### From the CLI

```bash
./space-router-node-linux-x64 --claim
./space-router-node-linux-x64 --claim --include-retryable      # also retry failed-retryable rows
./space-router-node-linux-x64 --claim --uuid abc-123…          # claim a specific receipt
```

The CLI prints a JSON summary:

```
{
  "submitted": 12,
  "claimed":   12,
  "skipped":   0,
  "tx_hash":   "0xabc…"
}
```

### Auto-claim

Auto-claim is an optional setting that submits a claim transaction automatically when your earnings cross a threshold. Enable it in **Settings**.

#### Thresholds (OR logic)

Auto-claim fires when **either**:

* Total claimable SPACE crosses your **amount threshold** (default **10 SPACE**), *or*
* Total claimable receipts crosses your **count threshold** (default **10 receipts**).

Lower the thresholds for more frequent (smaller) claims; raise them to amortize gas across larger batches.

{% hint style="info" %}
**Why opt in?**

Auto-claim is off by default because it spends CTC on its own schedule. Once you've fund your Identity wallet with enough CTC and seen claims succeed manually, turning on auto-claim is a "set and forget" option.
{% endhint %}

#### If auto-claim fails

The app sticks a banner on the status screen: *"Auto-claim failed: "* with three buttons:

* **Show log** — opens the relevant log file at the failing line.
* **Retry now** — re-attempts the claim.
* **Disable auto-claim** — turns off the feature so the banner stops returning.

The banner persists across restarts until you act on it.

### Receipt states & what to do

#### pending\_sign

The gateway hasn't returned a signature yet. Usually clears within a minute. No action.

#### claimable

Ready to settle. Click *Claim All Outstanding* or wait for auto-claim.

#### failed\_retryable

Sign or claim hit a transient error. The app will retry automatically; you can also click *Retry now*. Common causes:

| Error code                 | What it means                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `SIGN_TIMEOUT`             | Gateway didn't respond in time. Retries don't count toward the cap.                         |
| `CLAIM_RPC_UNREACHABLE`    | Creditcoin RPC was down. Retries don't count toward the cap.                                |
| `CLAIM_TX_TIMEOUT`         | Submitted, but confirmation took too long. The reaper auto-checks if it actually succeeded. |
| `SIGN_REJECTED_CLOCK_SKEW` | Your machine's clock drifted. Enable NTP / time sync.                                       |

#### failed\_terminal

Failed twice and won't be retried. The receipt is permanently locked. Reasons:

| Error code                        | What it means                                                                      | Fix                                                          |
| --------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `SIGN_REJECTED_UNREGISTERED_NODE` | Your wallet isn't registered in the escrow contract.                               | Wait for the next staking-approval cron, or contact support. |
| `SIGN_REJECTED_BYTE_MISMATCH`     | Gateway counted different bytes than your node reported.                           | Usually a one-off; if recurring, restart your node.          |
| `SIGN_REJECTED_PRICE_CAP`         | Receipt price exceeded the network cap.                                            | Should not happen in normal operation; report to support.    |
| `SIGN_REJECTED_BAD_SIGNATURE`     | Identity-key signature didn't verify.                                              | Check that `node-identity.key` hasn't been corrupted.        |
| `CLAIM_REVERTED`                  | On-chain claim reverted. Often "nonce already used" — receipt was already claimed. | Check Blockscout — usually no action needed.                 |
| `CLAIM_NONCE_ALREADY_USED`        | Receipt was settled in a prior batch.                                              | None — earnings already received.                            |

### The reaper

A background process called the reaper periodically reconciles stuck rows. If a claim transaction got submitted but the result is unclear (timeout, RPC blip), the reaper checks the on-chain state and marks the receipt as **claimed** if the contract recorded it. You can run a reaper tick on demand:

```bash
./space-router-node-linux-x64 --receipts --reap
```

### Tax & reporting

The Earnings screen's **History** section is your audit trail. Every claimed receipt has a Blockscout link with timestamp, batch size, and total SPACE transferred. Export the on-chain transactions of your collection wallet for accounting.