Sponsored Tasks: CLI Reference
Every taskmarket sponsored-task subcommand, plus the task create flags for sponsored tasks.
Install the CLI as described in the CLI reference; these commands ship in
CLI 1.14.0 and later.
Contents
- Requirements by command
- sponsored-task create
- sponsored-task fund
- sponsored-task managers add
- sponsored-task managers remove
- sponsored-task managers list
- sponsored-task fee-bank deposit
- sponsored-task fee-bank balance
- sponsored-task fee-bank withdraw
- sponsored-task list
- sponsored-task settlements
- sponsored-task show
- sponsored-task request-review
- sponsored-task balance
- sponsored-task withdraw
- sponsored-task exit
- sponsored-task claim
- sponsored-task rewards
- sponsored-task managed
- task create sponsored flags
Requirements by command
| Command | Keystore | TASKMARKET_RPC_URL | Native gas | Caller |
|---|---|---|---|---|
create | Yes | Yes | Yes | Anyone |
fund | Yes | Yes | Yes | Anyone |
managers add, managers remove | Yes | Yes | Yes | Vault owner |
managers list | No | No | No | Anyone |
fee-bank deposit, fee-bank withdraw | Yes | Yes | Yes | The manager |
fee-bank balance | Yes | Yes | No | The manager |
list, show, balance, settlements | No | No | No | Anyone |
withdraw, exit | Yes | Yes | Yes | Vault owner |
request-review | Yes | No | No | Vault owner |
claim | Yes | No | No | The worker |
rewards | Only without --address | No | No | Anyone |
managed | Only without --address | No | No | Anyone |
Commands that use TASKMARKET_RPC_URL stop with TASKMARKET_RPC_URL must be set to a chain RPC endpoint for vault administration commands when it is unset, and check that the endpoint's chain
matches --chain-id. Write commands simulate first, then send and wait for the receipt; a reverted
receipt fails with <function> reverted: <txHash>. Commands that need a keystore tell you to run taskmarket init when
there is none. Address flags must be
0x-prefixed 40-hex-digit addresses.
All amounts below are base units unless stated otherwise.
sponsored-task create
Create a new vault for a project token.
taskmarket sponsored-task create --factory <address> --chain-id <id> --token <address> [--owner <address>]| Option | Required | Meaning |
|---|---|---|
--factory <address> | Yes | SponsoredTaskFactory address. |
--chain-id <id> | Yes | Chain the factory is on. |
--token <address> | Yes | Project ERC-20 token. |
--owner <address> | No | Vault owner. Defaults to your wallet. |
Output: txHash, vault, vaultId, owner, token.
sponsored-task fund
Approve the vault and fund it with project tokens (two transactions).
taskmarket sponsored-task fund --vault <address> --token <address> --chain-id <id> --amount <baseUnits>| Option | Required | Meaning |
|---|---|---|
--vault <address> | Yes | Vault address. |
--token <address> | Yes | The vault's project token. |
--chain-id <id> | Yes | Chain the vault is on. |
--amount <baseUnits> | Yes | Amount in the token's base units. |
After the approval, the CLI waits up to 30 seconds for the RPC endpoint to report the allowance.
Output: txHash, vault, amount.
sponsored-task managers add
Authorize a manager, or change an existing manager's cap, and set it active.
taskmarket sponsored-task managers add --vault <address> --chain-id <id> --manager <address> --cap <baseUnits>| Option | Required | Meaning |
|---|---|---|
--vault <address> | Yes | Vault address. |
--chain-id <id> | Yes | Chain the vault is on. |
--manager <address> | Yes | Manager to authorize. |
--cap <baseUnits> | Yes | Lifetime spend cap in the token's base units. Must be at least the manager's current reserved plus spent. |
Output: txHash, manager, spendCap, active.
sponsored-task managers remove
Deactivate a manager. Does not reclaim tokens already reserved.
taskmarket sponsored-task managers remove --vault <address> --chain-id <id> --manager <address>The cap is pinned to the manager's current reserved plus spent. Output: txHash, manager,
spendCap, active.
sponsored-task managers list
taskmarket sponsored-task managers list --vault-id <vaultId>Output: an array of { vaultId, managerAddress, spendCap, spent, active }.
sponsored-task fee-bank deposit
Approve the fee bank and deposit USDC credit for creating sponsored tasks.
taskmarket sponsored-task fee-bank deposit --fee-bank <address> --usdc <address> --chain-id <id> --amount <baseUnits>| Option | Required | Meaning |
|---|---|---|
--fee-bank <address> | Yes | SponsoredTaskFeeBank address. |
--usdc <address> | Yes | USDC address on that chain. |
--chain-id <id> | Yes | Chain the fee bank is on. |
--amount <baseUnits> | Yes | USDC base units (6 decimals). |
Output: txHash, feeBank, deposited.
sponsored-task fee-bank balance
taskmarket sponsored-task fee-bank balance --fee-bank <address> --chain-id <id>Output: feeBank, manager (your wallet), creditBaseUnits.
sponsored-task fee-bank withdraw
Withdraw unused USDC credit.
taskmarket sponsored-task fee-bank withdraw --fee-bank <address> --chain-id <id> --amount <baseUnits> [--recipient <address>]--recipient defaults to your wallet. Output: txHash, recipient, withdrawn.
sponsored-task list
taskmarket sponsored-task list [--limit <n>] [--cursor <vaultId>] [--include-unverified]| Option | Default | Meaning |
|---|---|---|
--limit <n> | 50 | Maximum vaults to return. |
--cursor <vaultId> | none | Pagination cursor from a previous nextCursor. |
--include-unverified | off | Include vaults not yet curator-approved. |
Output: { vaults, nextCursor }.
sponsored-task settlements
List every settlement a vault has installed, across all epochs, newest first. Each row is one task.
taskmarket sponsored-task settlements <vaultId> [--limit <n>] [--cursor <cursor>]| Option | Default | Meaning |
|---|---|---|
--limit <n> | 25 | Maximum settlements to return, 1 to 100. |
--cursor <cursor> | none | Pagination cursor from a previous nextCursor. |
Output: { settlements, nextCursor }, printed as the API returns it, with amounts in the vault
token's base units. Each settlement's awardCount is the number of awards it paid, 0 when it
awarded nothing. See API reference for each field.
sponsored-task show
taskmarket sponsored-task show <vaultId>Output: the vault object (see API reference), including its
curationStatus, the curator's public curationNote and curatedAt, and reviewRequestedAt
while a curation review request is open.
sponsored-task request-review
Ask Taskmarket curators to review a vault. Signs a short-lived, single-use message with your wallet and submits it; nothing is sent on-chain.
taskmarket sponsored-task request-review <vaultId>Your wallet must be the vault's owner. The command stops with Vault is already approved for an
approved vault, and with Only the vault owner (<owner>) can request a review; your wallet is <address> for any other wallet, before signing.
Output: vaultId, reviewRequestedAt and alreadyOpen. alreadyOpen is true when the
vault already had an open request, in which case reviewRequestedAt is that request's time. If
the vault was reviewed or requested in the last 24 hours, the command fails with status 429 and
a hint saying when a new request is accepted. See Curation.
sponsored-task balance
taskmarket sponsored-task balance <vaultId>Output: fundedTotal, availableBalance, reservedBalance.
sponsored-task withdraw
Withdraw unreserved project tokens (owner only).
taskmarket sponsored-task withdraw --vault <address> --chain-id <id> --amount <baseUnits> [--recipient <address>]--recipient defaults to your wallet. Output: txHash, recipient, withdrawn.
sponsored-task exit
Terminally exit a vault. Sweeps every token, including reserved and unclaimed ones, to the recipient and voids every outstanding reservation, claim signature and Merkle proof. There is no undo.
taskmarket sponsored-task exit --vault <address> --chain-id <id> --yes [--recipient <address>]| Option | Required | Meaning |
|---|---|---|
--vault <address> | Yes | Vault address. |
--chain-id <id> | Yes | Chain the vault is on. |
--yes | Yes in practice | Without it the command stops with This is irreversible. Re-run with --yes to confirm the exit. |
--recipient <address> | No | Defaults to your wallet. |
Output: txHash, recipient, status (exited).
sponsored-task claim
Claim your unclaimed sponsored reward in a vault, gaslessly.
taskmarket sponsored-task claim <vaultId> [--task-id <id>]| Option | Meaning |
|---|---|
--task-id <id> | Claim the entitlement for this task. Defaults to the first unclaimed one. |
Requires a registered withdrawal address. Output: txHash, destination, amount. See
Claiming rewards.
sponsored-task rewards
List every sponsored reward a worker holds across all vaults, newest first: pending, claimable and already claimed.
taskmarket sponsored-task rewards [--address <address>] [--state <state>] [--claim-status <status>] [--limit <n>] [--cursor <cursor>]| Option | Default | Meaning |
|---|---|---|
--address <address> | Your wallet | Worker address to list. Without it the command needs a keystore. |
--state <state> | any | reserved, released, credited, defaulted or award_count_exceeded. |
--claim-status <status> | any | unclaimed, claim_pending or claimed. |
--limit <n> | 50 | Maximum rewards to return, 1 to 100. |
--cursor <cursor> | none | Pagination cursor from a previous nextCursor. |
Output: { rewards, nextCursor }. Each reward has taskId, vaultId, chainId,
vaultStatus, curationStatus, tokenAddress, tokenSymbol, tokenDecimals, leafIndex,
amount (your own net share in base units), the task's grossAmount, feeAmount, netAmount
and feeBps, rewardState, epoch, claimStatus, claimTxHash, claimedAt, claimable
and entitledAt. A reward with claimable: true can be claimed with
sponsored-task claim <vaultId> --task-id <taskId>. Wraps
GET /api/sponsored-task-rewards/workers/<workerAddress>; see
API reference.
sponsored-task managed
List the active vaults where an address is an active manager: the vaults it can fund a task from
with task create --sponsored-task.
taskmarket sponsored-task managed [--address <address>] [--limit <n>] [--cursor <vaultId>]| Option | Default | Meaning |
|---|---|---|
--address <address> | Your wallet | Manager address to list. Without it the command needs a keystore. |
--limit <n> | 50 | Maximum vaults to return, 1 to 100. |
--cursor <vaultId> | none | Pagination cursor from a previous nextCursor. |
Output: { vaults, nextCursor }. Each entry has vault (the vault object, including
availableBalance, token details and curationStatus) and manager (spendCap, spent,
reserved, remainingCap and active). remainingCap is what you can still reserve, in base
units. Wraps GET /api/sponsored-task-vaults/managed/<managerAddress>; see
API reference.
task create sponsored flags
taskmarket task create ... --sponsored-task <vaultId> --sponsored-task-tokens <amount>| Option | Meaning |
|---|---|
--sponsored-task <vaultId> | Fund this task from the vault, reserving --sponsored-task-tokens alongside the ordinary --reward. |
--sponsored-task-tokens <amount> | Whole-token amount to reserve, for example 100 for 100 tokens. Required with --sponsored-task. |
Cannot be combined with --hook-data. See
Creating sponsored tasks.