Skip to main content
Bounties are the core feature of the platform, allowing organizations to fund work and developers to earn by completing tasks. Each bounty represents a funded piece of work linked to GitHub issues or Linear tasks.

​
Bounty Lifecycle

Every bounty follows a structured lifecycle with distinct statuses:
1

Draft

Bounty is created but not yet funded. Only visible to the creator and organization members.
2

Open

Bounty is funded and available for developers to apply and submit work.
3

In Progress

A developer has been assigned and is actively working on the bounty.
4

Completed

Work has been approved and payment released to the contributor.
5

Cancelled

Bounty has been cancelled with payment refunded to the organization.

​
Creating a Bounty

Organizations can create bounties through the platform or by mentioning the bot in GitHub/Linear issues.

​
Required Information

  • Title: Clear, descriptive title (max 200 characters)
  • Description: Detailed requirements (minimum 10 characters)
  • Amount: Bounty value in USD or other supported currencies
  • Organization: Which team is funding this bounty

​
Optional Fields

  • Deadline: Target completion date
  • Tags: Categorize by technology or feature area
  • Repository URL: Link to the relevant repository
  • Issue URL: Link to GitHub issue or Linear task

​
Creating via API

const bounty = await trpc.bounties.createBounty.mutate({
  title: "Implement user authentication",
  description: "Add OAuth2 support with GitHub and Google providers",
  amount: "500.00",
  currency: "USD",
  deadline: "2026-04-15T00:00:00Z",
  tags: ["authentication", "backend"],
  issueUrl: "https://github.com/owner/repo/issues/123",
  payLater: false // Create and fund immediately
});

​
GitHub Integration

Bounties can be automatically linked to GitHub issues. The platform enforces one bounty per GitHub issue to prevent conflicts.

​
Automatic Issue Detection

When you provide an issue URL, the platform extracts:
  • Repository owner and name
  • Issue number
  • Validates no existing active bounty exists for that issue

​
Bot Comments

The GitHub bot automatically posts comments on linked issues showing:
  • Bounty amount and currency
  • Funding status
  • Submission instructions
  • Link to bounty detail page

​
Submission Keyword

Developers can submit work by commenting on the GitHub issue with the submission keyword (default: @bountydotnew submit).

​
Linear Integration

Bounties can also be linked to Linear issues with bi-directional sync:
  • Create bounties from Linear issues
  • Automatically mirror to GitHub issues
  • Sync status updates between platforms
  • Post bot comments in Linear

​
Payment Flow

​
Funding a Bounty

  1. Organization creates bounty with amount
  2. Platform calculates total including fees
  3. Stripe Checkout session initiated
  4. Payment held securely until completion
  5. Bounty status changes from draft to open
Bounties remain in draft status until payment is confirmed via Stripe webhook.

​
Payment Statuses

  • pending: Payment not yet initiated
  • held: Funds captured and held in escrow
  • released: Payment transferred to contributor
  • refunded: Payment returned to organization
  • failed: Payment processing error

​
Submissions

Developers submit completed work for review by the bounty creator.

​
Submission Process

  1. Developer applies to work on bounty (optional)
  2. Creator assigns bounty to developer
  3. Developer completes work and submits
  4. Creator reviews submission
  5. Creator approves, requests revisions, or rejects

​
Submission Requirements

  • Description: Explanation of work completed (min 10 characters)
  • Deliverable URL: Link to completed work (required)
  • Pull Request URL: Link to GitHub PR (optional)

​
Submission Statuses

  • pending: Awaiting review
  • approved: Accepted, payment released
  • rejected: Not accepted
  • revision_requested: Changes needed

​
Creating a Submission

const submission = await trpc.bounties.submitWork.mutate({
  bountyId: "bounty-uuid",
  description: "Implemented OAuth2 with GitHub and Google. Added tests and documentation.",
  deliverableUrl: "https://github.com/owner/repo/pull/456",
  pullRequestUrl: "https://github.com/owner/repo/pull/456"
});

​
Applications

Developers can apply to work on open bounties before starting work.
  • Submit application with message explaining approach
  • Creator reviews applications and assigns best candidate
  • Only one developer can be assigned per bounty
  • Applications track acceptance status and timestamps

​
Bounty Interactions

​
Voting

Users can upvote bounties to show interest:
  • One vote per user per bounty
  • Vote counts displayed publicly
  • Toggle vote on/off
  • Helps prioritize community-requested features

​
Bookmarking

Save bounties for later:
  • Bookmark bounties you want to track
  • View all bookmarked bounties in one place
  • Private to your account

​
Comments

Discuss bounties with threaded comments:
  • Ask clarifying questions
  • Provide updates on progress
  • Reply to other comments (nested threads)
  • Edit comments (original content preserved)
  • Like comments to show agreement
Organization members can pin important bounties:
  • Highlight priority work
  • Display prominently on organization profile
  • Only organization members can feature bounties

​
Cancellation

Bounties can be cancelled under certain conditions:

​
Cancellation Requests

Organizations can request to cancel funded bounties:
  • Submit cancellation request with reason
  • System reviews based on submissions and progress
  • Approved cancellations trigger refund
  • Cancelled bounties cannot be reopened

​
Cancellation Statuses

  • pending: Awaiting review
  • approved: Cancellation approved, refund processed
  • rejected: Cancellation denied
  • withdrawn: Request cancelled by requestor
Bounties with approved submissions cannot be cancelled. You must resolve the submission first.

​
Searching and Filtering

Find bounties using various filters: 
const bounties = await trpc.bounties.fetchAllBounties.query({
  page: 1,
  limit: 20,
  status: "open",
  search: "authentication",
  tags: ["backend", "security"],
  sortBy: "amount",
  sortOrder: "desc"
});

​
Filter Options

  • Status: Filter by lifecycle stage
  • Search: Text search in title and description
  • Tags: Filter by technology tags
  • Creator: View bounties from specific organization
  • Sort: By creation date, amount, deadline, or title

​
Best Practices

Clear Requirements

Provide detailed requirements and acceptance criteria to avoid confusion and revision requests.

Appropriate Pricing

Set bounty amounts that reflect the complexity and time required for the work.

Timely Communication

Respond to questions and applications promptly to keep developers engaged.

Fair Reviews

Review submissions objectively and provide constructive feedback when requesting revisions.

Build docs developers (and LLMs) love

Get started for freeTalk to us