API Reference

Integrate with zkGrants programmatically

API Overview

zkGrants provides REST APIs for querying grants, managing submissions, and initiating claims. The API is designed for building integrations, dashboards, and automated workflows.

Note: The API is currently in development. Some endpoints may change before the stable release.

Base URL

Production

https://api.zkgrants.com/v1

Authentication

API Keys

Some endpoints require authentication via API key or OAuth token. Include the key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Public endpoints (reading grants, etc.) do not require authentication.

Endpoints

GET/grants

List all grants with optional filters.

Query Parameters

Parameter	Type	Description
status	string	Filter by status: active, claimed, expired
chain	string	Filter by chain: ethereum, solana
repo	string	Filter by repository (owner/repo)
limit	number	Number of results (default: 20)
offset	number	Pagination offset

Example Response

{
  "grants": [
    {
      "id": "0x1234...abcd",
      "title": "Implement caching layer",
      "repo": "acme/backend",
      "chain": "ethereum",
      "award": {
        "token": "USDC",
        "amount": "5000"
      },
      "judgingMode": "ci",
      "status": "active",
      "deadline": "2024-02-01T00:00:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

GET/grants/:id

Get detailed information about a specific grant.

Example Response

{
  "id": "0x1234...abcd",
  "title": "Implement caching layer",
  "description": "Add Redis caching to reduce DB load...",
  "repo": "acme/backend",
  "targetBranch": "zkgrants/0x1234",
  "chain": "ethereum",
  "award": {
    "token": "USDC",
    "amount": "5000",
    "tokenAddress": "0xa0b8..."
  },
  "judgingMode": "ci",
  "requiredWorkflow": "tests.yml",
  "template": "winner-takes-all",
  "status": "active",
  "deadline": "2024-02-01T00:00:00Z",
  "claimDeadline": "2024-02-08T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "submissions": 3
}

GET/grants/:id/submissions

List submissions (PRs) for a specific grant.

Example Response

{
  "submissions": [
    {
      "id": "sub_abc123",
      "prNumber": 42,
      "prUrl": "https://github.com/acme/backend/pull/42",
      "author": "builder123",
      "status": "eligible",
      "workflowRuns": [
        {
          "id": 12345,
          "name": "tests.yml",
          "conclusion": "success",
          "completedAt": "2024-01-15T12:00:00Z"
        }
      ],
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

POST/claims/initiate

Initiate a claim for an eligible submission. Requires authentication.

Request Body

{
  "grantId": "0x1234...abcd",
  "submissionId": "sub_abc123",
  "recipientAddress": "0xYourWalletAddress..."
}

Example Response

{
  "claimId": "claim_xyz789",
  "status": "proof_generating",
  "estimatedTime": 180
}

GET/claims/:id/status

Check the status of a claim, including proof generation progress.

Example Response

{
  "claimId": "claim_xyz789",
  "grantId": "0x1234...abcd",
  "status": "ready",
  "proof": {
    "available": true,
    "expiresAt": "2024-01-16T12:00:00Z"
  },
  "transaction": {
    "ready": true,
    "estimatedGas": "150000"
  }
}

Webhooks

zkGrants can send webhook notifications for grant events. Configure webhooks in your account settings.

Available Events

grant.created— New grant published
grant.funded— Grant funded onchain
submission.eligible— Submission qualified
grant.claimed— Grant successfully claimed
grant.expired— Grant deadline passed

Webhook Payload

{
  "event": "grant.claimed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "grantId": "0x1234...abcd",
    "claimant": "builder123",
    "recipient": "0xWallet...",
    "txHash": "0xTransaction..."
  }
}

Rate Limits

Tier	Requests/min	Notes
Unauthenticated	60	Public endpoints only
Authenticated	300	With API key
Enterprise	Custom	Contact us

SDKs & Libraries

Official SDKs for common languages (coming soon):

📦

TypeScript

@zkgrants/sdk

🐍

Python

zkgrants-py

🦀

Rust

zkgrants-rs

Need Help?

Explore the rest of the documentation or get started with zkGrants.

Back to Docs Browse Grants