Sponsored Tasks: Claiming Rewards

If you win a sponsored task, you earn the task's USDC reward as usual plus a share of the project tokens reserved for it. The USDC reward settles through Taskmarket's normal path. The project tokens have to be claimed, and the claim is gasless.

Finding sponsored rewards

A task with a sponsored reward has a sponsoredTaskRewards array in its list and detail responses (taskmarket task get <taskId>). The field is absent on tasks without one. Read grossAmount, netAmount, tokenSymbol and tokenDecimals to see what is on offer, state to see where the reward is in its lifecycle, and curationStatus to see whether Taskmarket has reviewed the vault. See Overview.

You earn sponsored tokens in proportion to your share of the task's USDC award, from the same verdict. See How the reward is split.

Before your first claim: set a withdrawal address

A claim can only pay out to your registered withdrawal address. Without one, sponsored-task claim stops with No withdrawal address set. Run: taskmarket wallet set-withdrawal-address <address>.

taskmarket wallet set-withdrawal-address <address>

That command prints an account recovery code once. Save it somewhere safe: it is the only way to change the withdrawal address later. See Withdrawal address.

When a reward becomes claimable

A reward is claimable once its state is credited, which means the task's settlement has been installed in the vault. After the verdict, a Taskmarket keeper settles finished tasks on a 30 second cycle, so this normally follows the verdict within a short while. Until then, sponsored-task claim reports that it found nothing to claim.

Claiming

taskmarket sponsored-task claim <vaultId>

This claims your first unclaimed entitlement in that vault. If you have several, pass the task id to choose one, and run the command once per entitlement:

taskmarket sponsored-task claim <vaultId> --task-id <taskId>

You need no gas, no RPC endpoint and no project tokens. The response contains the claim's txHash, the destination it paid and the amount in token base units.

What happens during a claim

The CLI reads your withdrawal address and stops if there is none.
It fetches your unclaimed entitlements in the vault, each with its Merkle proof (GET /api/sponsored-task-vaults/<vaultId>/entitlements).
It reads your next claim nonce for the vault (GET /api/sponsored-task-vaults/<vaultId>/claim-nonce).
It signs an EIP-712 ClaimTo message with your wallet key. The domain is SponsoredTasksVault, version 1, on the vault's chain and address. The message binds the vault id, epoch, task, leaf index, your address, the destination, the amount, the nonce and a deadline 10 minutes ahead.
It posts the signed claim to POST /api/sponsored-task-vaults/<vaultId>/claim. The backend checks that the destination equals your registered withdrawal address, that the nonce is the next one, and simulates the claim before relaying claimTo on-chain.

Claims for one wallet in one vault go through one at a time, in nonce order. If the backend answers that a claim is in progress or the nonce is not next, the CLI retries under the same idempotency key for up to 60 seconds.

Claim errors

Message	Meaning
No keystore found. Run `taskmarket init` first.	The CLI has no wallet.
`No withdrawal address set. Run: taskmarket wallet set-withdrawal-address <address>`	Set a withdrawal address first.
`No unclaimed entitlement found for this wallet in this vault.`	Nothing to claim: the settlement is not installed yet, you have already claimed, you did not win a share, the `--task-id` is wrong, or the vault has been exited.
`No sponsored task reward for this task`	The task id has no sponsored reward.
`No settlement installed for this task yet`	Settlement has not landed; try again shortly.
`Claim authorization has expired`	The signed deadline passed before the relay. Run the claim again.
`destination does not match registered withdrawal address`	The signed destination is not your withdrawal address.
`Claim in progress, retry` / `Claim nonce not next, retry`	Another claim for your wallet in this vault is in flight. The CLI retries automatically.
`Claim nonce already used`	That nonce has been spent. Run the claim again to get a fresh nonce.
`Claim would revert: <ErrorName>`	The on-chain simulation failed. For example `VaultNotActive` (the vault was exited), `ClaimAlreadyPaid`, `InvalidClaimProof` or `InvalidClaimSignature`.

Read-only commands

These need no gas and no RPC endpoint:

taskmarket sponsored-task show <vaultId>
taskmarket sponsored-task balance <vaultId>
taskmarket sponsored-task list [--include-unverified]
taskmarket wallet get-withdrawal-address

The web app also lists sponsored task vaults and shows a claim control for credited rewards on a task you won.

Risks to know

The vault owner can exit the vault at any time before you claim, and your reward then becomes defaulted with nothing to claim. Claim promptly once a reward is credited.
An unverified or rejected vault has not been endorsed by Taskmarket.
Your USDC reward is never affected by either.

See Trust and safety.

Contents