<div align="center">

<img src="./.github/assets/banner.png" alt="GitEquity" width="100%" />

GitEquity

Own real stocks from a GitHub comment.

No brokerage account. No wallet app. No gas.

Website · Docs · Dashboard · X

</div>

---

The one-line version

You type this in a GitHub issue:

@gitequitybot buy $NVDA 100

A vault gets deployed on-chain under your GitHub ID, 100 USDG gets swapped for gitNVDA through Uniswap V3, and the position sits in your vault until you sell or withdraw. You never opened a wallet. You never paid gas.

---

Contents

• Why this exists
• How a command becomes a trade
• Security model
• Contracts
• Assets
• Bot commands
• MCP: trade from your AI client
• Repository layout
• Running locally
• Environment
• Related repositories

---

Why this exists

Every developer already has an identity that is stable, public, and hard to fake casually: their GitHub account. GitEquity treats that account as the primary key for a brokerage.

The consequences are practical rather than philosophical:

• Onboarding is zero steps. If you can comment on an issue, you have an account.
• Identity is permanent. Vaults bind to the numeric GitHub user ID, which GitHub never reuses and never changes. Rename your handle, keep your money.
• The interface is the workflow. Bounties, payouts, and treasury moves happen where the work already happens.

---

How a command becomes a trade

GitHub comment
      |
      v
  Webhook  ──►  Intent parser  ──►  Relayer  ──►  GitEquityVault
                                                        │
                                                  Uniswap V3
                                                        │
                                                  gitNVDA, gitTSLA, ...

1. issue_comment webhook fires, signature verified against GITHUB_WEBHOOK_SECRET
2. Command text is parsed into a structured intent: ticker, side, size
3. Vault is looked up by GitHub user ID, or deployed on first use
4. Relayer signs a short-lived authorization and submits the transaction, paying gas
5. Vault routes USDG through Uniswap V3 and holds the resulting stock token
6. Bot edits its own comment in place with the transaction hash and new balance

---

Security model

The vault requires two independent signatures for every state-changing call:

Signature	Held by	Covers
ownerSig	Per-user keypair, AES-256-GCM encrypted at rest	Vault address, GitHub user ID, nonce, deadline
relayerSig	Relayer signing key, hot	Issued only after a GitHub command is verified

Neither key alone moves funds. The owner key never pays gas and never appears as msg.sender. Replay is blocked by a monotonic nonce plus a five-minute deadline carried inside every signature.

Swap outputs are constrained to an on-chain whitelist, so a compromised relayer cannot route a swap into an attacker-controlled token.

---

Contracts

Contract	Role
GitEquityVaultFactory	Deploys exactly one soul-bound vault per GitHub user ID
GitEquityVault	Custody and swap execution, dual-signature gated
GitEquityStockFactory	Deploys the ERC-20 receipt token for each ticker
GitEquityStockToken	Soul-bound receipt: gitNVDA, gitTSLA, gitAAPL, ...
GitEquityToken	Native EQUITY token
GitEquityAirdrop	Merkle distributor for EQUITY

Sources and deploy scripts live in gitequity-contracts. Addresses are published to deployments.json after each deploy.

---

Assets

62 tokenized equities on Robinhood Chain, each verified on-chain through symbol() and decimals(). The registry lives in packages/rwa/src/registry.ts.

A sample of what is tradeable:

Ticker	Receipt	Ticker	Receipt
NVDA	gitNVDA	TSLA	gitTSLA
AAPL	gitAAPL	MSFT	gitMSFT
AMZN	gitAMZN	GOOGL	gitGOOGL
META	gitMETA	COIN	gitCOIN
AMD	gitAMD	AVGO	gitAVGO

Settlement is USDG. Pools are the 1% fee tier for single names, 0.3% for index products.

---

Bot commands

Tag @gitequitybot in any issue, pull request, or discussion comment.

Command	Example	Effect
buy $TICKER AMOUNT	buy $NVDA 100	Buy $100 of NVDA
sell $TICKER AMOUNT	sell $TSLA 50	Sell $50 of TSLA
sell all $TICKER	sell all $AAPL	Close the whole position
swap $FROM $TO	swap $NVDA $TSLA	Rotate one position into another
portfolio	portfolio	Holdings, cost basis, current value
balance	balance	USDG balance
deposit	deposit	Your deposit address and instructions
withdraw $TICKER	withdraw $NVDA	Send tokens to a linked wallet
confirm <code>	confirm 8F2A	Approve a write initiated from an AI client

Try them without spending anything in the playground.

---

MCP: trade from your AI client

GitEquity ships an MCP server, so Claude, Cursor, ChatGPT and others can read your portfolio directly.

Reads are direct. Writes always require a confirmation code posted from your GitHub account - the assistant proposes, you approve. An AI client cannot move your money on its own.

{
  "mcpServers": {
    "gitequity": {
      "url": "https://gitequity.xyz/api/mcp",
      "transport": "streamable-http"
    }
  }
}

Per-client setup guides: gitequity.xyz/mcp.

---

Repository layout

gitequity/
├── apps/
│   ├── api/            Express server, webhook handler, relayer, MCP endpoint
│   ├── web/            React + Vite frontend: landing, docs, dashboard
│   └── social-cards/   OG image generator
├── packages/
│   ├── db/                Drizzle schema and migrations
│   ├── rwa/               Asset registry and price feeds
│   ├── rh-swap/           Uniswap V3 quote and calldata helpers
│   ├── mcp/               MCP tool definitions and handlers
│   ├── x402/              x402 payment protocol
│   ├── api-spec/          OpenAPI spec, single source of truth
│   ├── api-zod/           Zod validators generated from the spec
│   └── api-client-react/  React Query hooks generated from the spec
├── scripts/            Dev and deploy tooling
└── tests/

The API contract flows one way: edit packages/api-spec, regenerate api-zod and api-client-react. Server and client cannot drift.

---

Running locally

Requirements: Node 20+, pnpm 9+, PostgreSQL 15+

git clone https://github.com/gitequityorg/gitequity.git
cd gitequity
pnpm install
cp .env.example .env      # fill in the values below
pnpm --filter @workspace/db run migrate
pnpm dev

API comes up on :3000, web on :5173.

To exercise the bot locally, point your GitHub App webhook at a tunnel such as ngrok http 3000, then comment in a repository where the App is installed.

---

Environment

Variable	What it is
GITHUB_APP_ID	Numeric ID of your GitHub App
GITHUB_APP_PEM	App private key, newlines escaped as \n
GITHUB_CLIENT_ID	OAuth client ID
GITHUB_CLIENT_SECRET	OAuth client secret
GITHUB_WEBHOOK_SECRET	Shared secret for webhook signature checks
SESSION_SECRET	Session signing key, 32+ characters
ENCRYPTION_MASTER_KEY	32-byte hex, wraps every stored user private key
DEPLOYER_PRIVATE_KEY	Deploys vaults and receipt tokens, pays gas
RELAYER_SIGNING_KEY	Signs execution authorizations
DATABASE_URL	PostgreSQL connection string

ENCRYPTION_MASTER_KEY cannot be rotated without re-encrypting every stored key. Back it up before going anywhere near production.

---

Related repositories

Repository	Contents
gitequity-contracts	Solidity sources, Hardhat config, deploy scripts
gitequity-mcp	Standalone MCP server
gitequity-mobile	Expo app
autogit	AI-assisted GitHub App builder
playground	Safe repository for trying bot commands

---

License

Apache 2.0. See LICENSE and NOTICE.