<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.

[![Chain](https://img.shields.io/badge/Robinhood_Chain-4663-DCF012?style=for-the-badge&labelColor=0A0A0A)](https://robinhoodchain.blockscout.com)
[![Solidity](https://img.shields.io/badge/Solidity-0.8.34-363636?style=for-the-badge&labelColor=0A0A0A&logo=solidity)](https://soliditylang.org)
[![Node](https://img.shields.io/badge/Node-20+-339933?style=for-the-badge&labelColor=0A0A0A&logo=node.js&logoColor=white)](https://nodejs.org)
[![License](https://img.shields.io/badge/License-Apache_2.0-DCF012?style=for-the-badge&labelColor=0A0A0A)](LICENSE)

[Website](https://gitequity.xyz) · [Docs](https://gitequity.xyz/docs) · [Dashboard](https://gitequity.xyz/app/dashboard) · [X](https://x.com/Git_Equity)

</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](#why-this-exists)
- [How a command becomes a trade](#how-a-command-becomes-a-trade)
- [Security model](#security-model)
- [Contracts](#contracts)
- [Assets](#assets)
- [Bot commands](#bot-commands)
- [MCP: trade from your AI client](#mcp-trade-from-your-ai-client)
- [Repository layout](#repository-layout)
- [Running locally](#running-locally)
- [Environment](#environment)
- [Related repositories](#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`](https://github.com/gitequityorg/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](https://github.com/gitequityorg/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.

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

Per-client setup guides: [gitequity.xyz/mcp](https://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+

```bash
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](https://github.com/gitequityorg/gitequity-contracts) | Solidity sources, Hardhat config, deploy scripts |
| [gitequity-mcp](https://github.com/gitequityorg/gitequity-mcp) | Standalone MCP server |
| [gitequity-mobile](https://github.com/gitequityorg/gitequity-mobile) | Expo app |
| [autogit](https://github.com/gitequityorg/autogit) | AI-assisted GitHub App builder |
| [playground](https://github.com/gitequityorg/playground) | Safe repository for trying bot commands |

---

## License

Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).