Bounties
Six routes read and act on bounties posted against sealed models through the bounty program (bountyProgramId in GET /v1/config, built on voynich-cpi). On the site, /bounties uses these routes directly.
A bounty is posted in one transaction and won in a single drawer signature: draw registers bounty::on_receipt as a Voynich settlement callback, so settle_call verifies the settled Receipt and pays the reward to the drawer inside the same transaction.
| Step | Route |
|---|---|
| Post a bounty reward in escrow | POST /v1/bounties/build, then POST /v1/transactions/submit |
| Draw, settle and pay in one signature | POST /v1/bounties/{address}/draw/build, submit, then send the encrypted input to POST /v1/calls/{id}/input with addresses.call |
| Collect a pre-callback attempt manually | POST /v1/bounties/{address}/collect/build, then submit |
| Cancel an open bounty as its creator | POST /v1/bounties/{address}/cancel/build, then submit |
In every path, {address} is the Bounty account's address. The errors every route shares are in Overview.
Bounty#
addressaddressrequiredThe Bounty PDA account.
creatoraddressrequiredThe wallet that posted and funded the bounty.
noncedecimal stringrequiredThe unsigned 64-bit nonce that derives the Bounty PDA with creator.
modeladdressrequiredThe sealed Model account that classifies attempts.
modelNamestring or nullrequiredThe model's name, when indexed.
targetLabelstring, 1 to 32 bytesrequiredThe label the model's verified open answer must match to win the bounty.
rewardMoneyrequiredThe reward held in escrow, as a Money.
statusstringrequiredopen: taking draw attempts. claimed: paid out to winner. cancelled: refunded to creator.
winneraddress or nullrequiredThe drawer paid when status is claimed.
winningCalladdress or nullrequiredThe Call account that won the bounty.
winningReceiptaddress or nullrequiredThe Receipt account verified by on_receipt (or collect for legacy attempts).
createdSlotslotrequiredThe slot the bounty was posted in.
claimedSlotslot or nullrequiredThe slot the bounty was claimed in, or null.
attemptsdecimal stringrequiredNumber of draw attempts opened against this bounty.
BountyAttempt#
addressaddressrequiredThe Attempt PDA account, derived from bounty and call.
bountyaddressrequiredThe Bounty account.
draweraddressrequiredThe wallet that paid the model's call price and receives the reward if the label matches.
calladdressrequiredThe Voynich Call account opened via CPI by the bounty program's caller PDA.
createdSlotslotrequiredThe slot the attempt opened in.
refundedbooleanrequiredtrue if an expired attempt call was refunded.
GET /v1/bounties#
Lists bounties, one page at a time.
statusstringFilter by open, claimed or cancelled. All statuses when omitted.
modeladdress or nameFilter to bounties targeting one model.
cursorstringSee Pagination.
limitinteger, 1 to 10024 when omitted.
Returns a page whose items are Bounty objects.
GET /v1/bounties/{address}#
Reads one bounty and its recorded attempts, latest attempt first.
bountyBountyrequiredThe Bounty.
attemptsarray of BountyAttemptrequiredEvery BountyAttempt recorded for this bounty.
| Code | When |
|---|---|
VALIDATION_ERROR | {address} is not an address. |
BOUNTY_NOT_FOUND | No bounty has this address. |
POST /v1/bounties/build#
Builds post: creates a Bounty PDA and moves reward (SOL or any SPL Token mint) into the bounty's escrow.
POST /v1/bounties/build
Content-Type: application/json
{
"wallet": "<creator address>",
"model": "sketch-32",
"targetLabel": "star",
"reward": { "amount": "20000000", "mint": null, "decimals": 9, "symbol": "SOL" },
"nonce": "<optional unsigned 64-bit integer>"
}walletaddressrequiredThe creator wallet. Pays rent, the transaction fee and the escrowed reward.
modeladdress or namerequiredThe target model (such as sketch-32).
targetLabelstring, 1 to 32 bytesrequiredThe label that wins the bounty.
rewardMoneyrequiredThe reward amount and mint (mint: null for SOL).
noncedecimal string, unsigned 64-bitA nonce unused by wallet. Drawn randomly when omitted.
Returns a Build with action: "post_bounty" and addresses: { model, bounty }.
| Code | When |
|---|---|
PROGRAM_UNAVAILABLE | The bounty program is not configured on this API. Retryable. |
MODEL_NOT_FOUND | No model has this name or address. |
INSUFFICIENT_FUNDS | wallet holds less than the reward, rent and fee. |
SIMULATION_FAILED | Refused by the bounty program in simulation. |
POST /v1/bounties/{address}/draw/build#
Builds draw: transfers the model's call price from the drawer to the bounty's caller PDA, creates the drawer's reward associated token account idempotently for SPL bounties, invokes voynich_cpi::open_call_with_callback in open answer mode with bounty::on_receipt as the settlement callback, and records an Attempt PDA.
POST /v1/bounties/<bounty address>/draw/build
Content-Type: application/json
{
"wallet": "<drawer address>",
"enclave": "<enclave address>",
"inputHash": "<sha-256 of the input envelope, 64 hex characters>",
"nonce": "<optional unsigned 64-bit integer>"
}walletaddressrequiredThe drawer. Pays the model's call price, rent and transaction fee, and receives the bounty if the settled answer matches targetLabel.
enclaveaddressrequiredThe live, reachable Enclave account holding a grant for the bounty's model.
inputHashhashrequiredSHA-256 of the encrypted input envelope sent next to POST /v1/calls/{id}/input.
noncedecimal string, unsigned 64-bitCall nonce for the bounty's caller PDA. Drawn randomly when omitted.
Returns a Build with action: "draw_bounty" and addresses: { model, bounty, attempt, call }.
| Code | When |
|---|---|
PROGRAM_UNAVAILABLE | The bounty program is not configured on this API. Retryable. |
BOUNTY_NOT_FOUND | No bounty has this address. |
BOUNTY_NOT_OPEN | The bounty is already claimed or cancelled. |
MODEL_NOT_FOUND, ENCLAVE_NOT_FOUND, MODEL_NOT_LIVE, GRANT_REQUIRED, ENCLAVE_EXPIRED, MEASUREMENT_NOT_ALLOWED | As on POST /v1/calls/build. |
INSUFFICIENT_FUNDS | wallet holds less than the model's call price, rent and fee. |
Next: sign and submit the Build, send the encrypted input envelope to POST /v1/calls/{id}/input using addresses.call, and wait for settlement. When the settled label matches targetLabel, settle_call invokes bounty::on_receipt and pays the reward to wallet in the same transaction. Poll GET /v1/bounties/{address} to observe status: "claimed" and winningCall.
POST /v1/bounties/{address}/collect/build#
Builds collect: invokes voynich_cpi::read_receipt on chain to verify the settled Receipt for call and pays the bounty reward to the attempt's drawer when the on-chain open answer's label matches targetLabel. Attempts opened with draw settle and pay automatically via on_receipt; collect remains available for pre-callback attempts.
POST /v1/bounties/<bounty address>/collect/build
Content-Type: application/json
{
"wallet": "<signer address>",
"call": "<call address from draw>"
}walletaddressrequiredThe signer paying the transaction fee (and any missing SPL token account rent for the winner). Any wallet may submit collect; the reward always lands in the attempt's drawer.
calladdressrequiredThe Call account opened by draw.
Returns a Build with action: "collect_bounty" and addresses: { model, bounty, attempt, call }.
| Code | When |
|---|---|
PROGRAM_UNAVAILABLE | The bounty program is not configured on this API. Retryable. |
BOUNTY_NOT_FOUND | No bounty has this address. |
BOUNTY_NOT_OPEN | The bounty is already claimed or cancelled. |
CALL_NOT_FOUND | No bounty attempt exists for {address} and call. |
PROGRAM_REFUSED | The Receipt does not match targetLabel (LabelMismatch) or is not a valid open Receipt for this attempt. |
POST /v1/bounties/{address}/cancel/build#
Builds cancel: refunds an open bounty's full escrow back to its creator.
POST /v1/bounties/<bounty address>/cancel/build
Content-Type: application/json
{
"wallet": "<creator address>"
}walletaddressrequiredThe bounty's creator. Must match the creator recorded in the Bounty account.
Returns a Build with action: "cancel_bounty" and addresses: { model, bounty }.
| Code | When |
|---|---|
PROGRAM_UNAVAILABLE | The bounty program is not configured on this API. Retryable. |
BOUNTY_NOT_FOUND | No bounty has this address. |
BOUNTY_NOT_OPEN | The bounty is already claimed or cancelled. |
SIMULATION_FAILED | wallet is not the bounty's creator. |