@gitnullxyz/sdk

JavaScript/TypeScript SDK for GitNull — full API client with typed hooks for Node.js and browser.

gitnull.xyz · API Reference · Docs

---

Installation

npm install @gitnullxyz/sdk
# or
pnpm add @gitnullxyz/sdk

---

Quick Start

import { GitNullClient } from '@gitnullxyz/sdk';

const client = new GitNullClient({
  baseUrl: 'https://gitnull.xyz',
  apiKey: process.env.GITNULL_API_KEY,
});

// List repositories
const repos = await client.repositories.list();

// Get platform stats
const stats = await client.stats.get();
console.log(`\$GNULL paid out: ${stats.gnullPaidOut}`);

// Get contributor profile
const contributor = await client.contributors.get('vitalik_dev');
console.log(`Reputation: ${contributor.reputation}`);

---

React Hooks (TanStack Query)

import { useListRepositories, useGetStats, useListBounties } from '@gitnullxyz/sdk/react';

function Dashboard() {
  const { data: repos } = useListRepositories();
  const { data: stats } = useGetStats();
  const { data: bounties } = useListBounties();

  return (
    <div>
      <p>Repositories: {repos?.length}</p>
      <p>PRs merged: {stats?.prsMerged}</p>
      <p>Active bounties: {bounties?.length}</p>
    </div>
  );
}

---

API Reference

Repositories

// List all repositories
await client.repositories.list({ search?: string, language?: string });

// Get a specific repository
await client.repositories.get(id: number);

// Create a repository
await client.repositories.create({ name, description, language });

// Get agent report for a repository
await client.repositories.getAgentReport(id: number);

Pull Requests

// List pull requests
await client.pullRequests.list();

// Get a pull request
await client.pullRequests.get(id: number);

// Create a pull request
await client.pullRequests.create({ repoId, title, body, author, additions, deletions });

// Merge a pull request (mints onchain proof)
await client.pullRequests.merge(id: number);

Bounties

// List bounties
await client.bounties.list();

// Get a bounty
await client.bounties.get(id: number);

// Create a bounty
await client.bounties.create({ issueId, amount, currency });

// Settle a bounty
await client.bounties.settle(id: number, { contributorId });

Contributors

// List contributors (leaderboard)
await client.contributors.list();

// Get contributor profile
await client.contributors.get(username: string);

Stats

// Get platform statistics
await client.stats.get();
// Returns: { totalRepositories, prsMerged, onchainProofs, activeBounties, gnullPaidOut }

Activity

// Get activity feed
await client.activity.list();

---

Onchain Integration

import { ContribLedger } from '@gitnullxyz/sdk/onchain';
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://rpc.gitchain-l2.xyz');
const ledger = new ContribLedger(provider);

// Get all contributions for a wallet
const contributions = await ledger.getContributions('0xYourWallet');

// Listen for new merge proofs
ledger.on('MergeProofMinted', (contributor, repoId, prNumber, tokenId) => {
  console.log(`New proof: PR #${prNumber} in repo ${repoId} → token #${tokenId}`);
});

---

TypeScript

The SDK is written in TypeScript and ships full type definitions. All API responses are typed with Zod schemas — the same schemas used by the GitNull API server.

import type { Repository, PullRequest, Bounty, Contributor } from '@gitnullxyz/sdk';

---

Links

• Platform: gitnull.xyz
• API Reference: gitnull.xyz/reference
• npm: @gitnullxyz/sdk
• CLI: gnull-cli

---

License

MIT © GitNull Protocol Labs