Documentation

How GitForge works — for maintainers and contributors. For protocol details and contract addresses, see the API reference.

Concepts

Bounty

A reward attached to a GitHub issue. Funded by the maintainer in escrow on Base. Identified globally by keccak256("github:owner/repo#issue").

Escrow

A smart contract on Base that locks funds. Only the bounty creator can cancel, release, or dispute. The arbiter resolves disputes.

Attestation

A non-transferable onchain proof that a contributor completed a bounty. Useful for portable reputation.

Bot

A GitHub App that watches comments, posts replies, and calls release() automatically on PR merge.

Maintainer flow

Install the GitHub App

Visit /install and pick the repo you want to use bounties on.

Open or pick an issue

Anything well-scoped works best. Add acceptance criteria so contributors know when it's done.

Post the bounty

Comment /bounty 0.001 ETH on the issue. The bot replies with a funding link.

Sign and fund escrow

Click the link, connect your wallet, and confirm the transaction. The 3% protocol fee is deducted up front.

Wait for a claim

Contributors will see the bounty on the explorer or comment /claim on the issue. First valid claim locks the bounty.

Review the PR

Once a PR with Closes #N in the body is merged, the bot auto-releases payment. For manual control, use the actions on the bounty page.

Contributor flow

Find a bounty

Browse the bounties page or watch your favorite repos.

Claim it

Comment /claim on the issue. The bot DMs you a one-time link to lock the bounty with your wallet (no funds spent — claim is free).

Build and submit

Open a PR that references the issue with Closes #N.

Mark as submitted

On the bounty page, click Mark submitted once your PR is open.

Get paid

When the PR merges, the bot releases payment to your wallet. You also receive an onchain attestation.

Issue commands

Command	Who	Effect
/bounty <amount> <token>	Maintainer	Bot replies with a prefilled funding link.
/claim	Contributor	Bot replies with a one-time claim link.

Token currently supported: ETH. ERC-20 (USDC) is wired in the contract but not yet exposed in commands.

Status states

Status	Meaning	Possible next
Open	Funded, awaiting a claim.	Claimed, Cancelled, Expired
Claimed	Locked by a contributor.	Submitted, Cancelled, Disputed
Submitted	Contributor marked work complete.	Completed (release), Disputed
Disputed	Arbiter resolves.	Completed, Cancelled
Completed	Paid out — terminal.	—
Cancelled	Refunded — terminal.	—
Expired	Past deadline, refunded minus fee — terminal.	—

Frequent questions

Does GitForge hold my funds?

No. Funds go directly into the escrow contract you sign for. The bot only triggers state transitions you authorise — bot can't move funds out of escrow except by release(), which is bounded by the contract logic.

What's the fee?

3% on funding. Refunds on cancellation are full; expirations refund the principal but the fee is kept.

Where is this deployed?

Base mainnet (chain id 8453).

What if a contributor submits low-quality work?

Maintainer can call dispute() from the dashboard. The arbiter then decides between release (to contributor) and refund (to maintainer).

Can I close a bounty without paying out?

Yes — cancel if no one has claimed yet (full refund), or wait for the deadline and call expire (refund minus fee).

Roadmap cleanup

Mainnet readiness

GitForge runs on Base mainnet with multisig role setup and audit pass.

Outbound webhooks

Planned events include bounty lifecycle updates and attestation mints, signed with HMAC and delivered with retry logs.

Security review

Pre-mainnet scope includes Slither, Echidna, external audit, and a scoped bug bounty for escrow and state-transition issues.

Marketplace listing

GitHub App listing prep tracks app metadata, permission rationale, screenshots, and install flow verification.

Programmatic access

GitForge ships three integration surfaces for agents, scripts, and apps.

Tool	Use it for	Default endpoint
CLI	Terminal workflows, quick lookups, bounty IDs, and stats.	https://api.gitforge.work
SDK	TypeScript apps, dashboards, bots, and test scripts.	https://api.gitforge.work
MCP	AI assistants that need GitForge tools inside Claude/Cursor/Codex-style clients.	https://api.gitforge.work

CLI

The CLI is published from @gitforge/mcp and exposes the gitforge binary.

# from this monorepo
cd mcp
npm install
npm run build
npm link

# configure production API
export GITFORGE_API_URL=https://api.gitforge.work

# common commands
gitforge list
gitforge active
gitforge list --status Open --repo owner/repo
gitforge get github:owner/repo#123
gitforge id github:owner/repo#123
gitforge stats
gitforge chain

Supported command groups: list, active, get, stats, id, parse, and chain.

SDK

Use @gitforge/sdk when you need typed API calls, bounty ID utilities, ABIs, or onchain reads/writes.

import { GitForgeClient, computeBountyId } from "@gitforge/sdk";

const client = new GitForgeClient({
  baseUrl: "https://api.gitforge.work",
});

const bountyId = computeBountyId("github:owner/repo#123");
const bounty = await client.getBounty(bountyId);
const open = await client.listBounties({ status: ["Open"], limit: 20 });
const stats = await client.getStats();

Main exports: GitForgeClient, GitForgeContract, computeBountyId, parseIssueUri, escrowAbi, attestationAbi, and shared response types.

MCP server

The MCP server exposes GitForge read tools to AI clients over stdio. It uses GITFORGE_API_URL for the bot API and RPC_URL for chain metadata.

# build the server
cd mcp
npm install
npm run build

# example MCP client config
{
  "mcpServers": {
    "gitforge": {
      "command": "node",
      "args": ["/absolute/path/to/bountykit/mcp/dist/index.js"],
      "env": {
        "GITFORGE_API_URL": "https://api.gitforge.work",
        "RPC_URL": "https://mainnet.base.org",
        "CHAIN_ID": "8453"
      }
    }
  }
}

MCP tools include listing bounties, fetching bounty detail, computing issue bounty IDs, reading platform stats, and checking chain configuration.

HTTP API

The bot also exposes read endpoints for dashboards and integrations:

GET  /api/stats
GET  /api/bounties?status=Open&limit=20
GET  /api/bounties/:bountyId

Full schema and examples in the API reference.