API reference

Read endpoints are CORS-enabled for the dashboard origin. Write endpoints expect onchain confirmation — the bot never custodies funds, it only verifies receipts and updates DB rows.

Base URL

https://api.gitgrant.app

Auth

None. Read endpoints are public. Write endpoints derive identity from txHash (the bot reads tx.from and validates receipts onchain), so spoofing fails at the receipt-decode step.

Onchain references

Chain

Base mainnet (chain id 8453)

Escrow

0xFa59AeA9A35880716bC17455d101871Ba2D274a7

Attestation

0xcb0Fc916dB192C49657433E31502a60Ee622213E

Bounty id

keccak256(abi.encodePacked(issueUri))

Endpoints

Response

{ "status": "ok", "service": "bountykit-bot" }

Response

{
  "stats": {
    "total": 12,
    "open": 4,
    "claimed": 2,
    "submitted": 1,
    "completed": 5,
    "totalEscrowedWei": "5000000000000000",
    "totalPaidWei": "2500000000000000"
  }
}

Query parameters

status	string	Open \| Claimed \| Submitted \| Disputed \| Completed \| Cancelled \| Expired
repo	string	Filter by `owner/repo`.
limit	number	Max rows (default 50, max 100).
offset	number	Pagination offset.

Example

https://api.gitgrant.app/api/bounties?status=Open&limit=20

Response

{
  "bounties": [
    {
      "bountyId": "0xa1b2…",
      "issueUri": "github:OrexaMine/bountykit-test#3",
      "repo": "OrexaMine/bountykit-test",
      "issueNumber": 3,
      "amountWei": "1000000000000000",
      "token": "0x0000000000000000000000000000000000000000",
      "status": "Open",
      "deadline": "2026-05-27T00:00:00.000Z",
      "createTx": "0x…"
    }
  ],
  "total": 12
}

Response

{
  "bounty": {
    "bountyId": "0xa1b2…",
    "issueUri": "github:OrexaMine/bountykit-test#3",
    "repo": "OrexaMine/bountykit-test",
    "issueNumber": 3,
    "amountWei": "1000000000000000",
    "token": "0x0000…",
    "status": "Submitted",
    "creatorWallet": "0x143c…",
    "claimantWallet": "0xfeed…",
    "createTx": "0x…",
    "claimTx": "0x…",
    "submitTx": "0x…",
    "releaseTx": null,
    "deadline": "2026-05-27T00:00:00.000Z"
  }
}

Response

{
  "intent": {
    "token": "01J…",
    "bountyId": "0xa1b2…",
    "issueUri": "github:OrexaMine/bountykit-test#3",
    "githubUsername": "alice",
    "expiresAt": "2026-05-21T00:00:00.000Z"
  }
}

Body (application/json)

token	string	Claim intent token from /api/claim-intents/:token.
txHash	string	0x-prefixed transaction hash.
walletAddress	string	EOA that signed the claim.

Response

{ "ok": true, "bountyId": "0xa1b2…" }

Body (application/json)

bountyId	string	0x bountyId.
txHash	string	submit() tx hash.
prUrl	string	Link to the PR (optional but recommended).

Response

{ "ok": true }

Body (application/json)

issueUri	string	github:owner/repo#N
walletAddress	string	Maintainer EOA.
txHash	string	createBountyETH tx hash.
githubUsername	string	Optional, for display only.

Response

{ "ok": true, "bountyId": "0xa1b2…" }

Errors

Errors are returned as { "error": "<reason>" } with a 4xx status. Common reasons:

missing_fields

invalid_issue_uri

invalid_tx_hash

invalid_wallet

tx_reverted

bounty_created_event_not_found

issue_uri_mismatch

wallet_not_creator