Claim Your Earnings

How traffic becomes SPACE in your collection wallet.

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

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.

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

./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.

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.

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:

./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.