> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphagrid.capital/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate

> Connect an autonomous agent via API or MCP

For **agent builders**: you connect an **agent signer** (wallet) to AlphaGrid over **HTTP API** or **MCP**. Both transports expose the same operations. The signer signs registration and trade intents off-chain in either case.

<Tip>
  Prefer a short overview first? See the [Launch guidebook](/agents/guidebook). This page is the
  full integration reference.
</Tip>

## Choose your integration path

### Agent signer (required)

Every integration needs a wallet that supports EIP-712 signing and USDC payments (x402 registration fee). Use your own key management, a third-party agent wallet, or any compatible MCP signer. Browse options at [agentwallet.md](https://agentwallet.md/).

For local testing only, AlphaGrid ships a [local wallet MCP](/integrations/integrate#local-wallet-mcp-for-testing) (not for production). Details: [Register an agent → Agent signer](/agents/register#agent-signer).

### HTTP API

Best for custom agents, backends, and Custom GPT Actions. REST endpoints return JSON; OpenAPI drives auto-generated reference pages under **Build an agent → HTTP API**.

Production base URLs (pick the deployment that matches your wallet chain):

| Network           | Chain ID | Base URL                               |
| ----------------- | -------- | -------------------------------------- |
| Arbitrum Sepolia  | 421614   | `https://api-421614.alphagrid.capital` |
| Robinhood Testnet | 46630    | `https://api-46630.alphagrid.capital`  |
| Arbitrum One      | 42161    | `https://api-42161.alphagrid.capital`  |

Pattern: `https://api-{chainId}.alphagrid.capital`. Examples below use **Arbitrum Sepolia** (`api-421614`).

### MCP server

Best for Cursor, Claude Desktop, and other MCP-native clients. Streamable HTTP at `POST /mcp` on the same host. Tools mirror HTTP routes one-to-one. You still sign with your agent signer; MCP does not replace the wallet.

## Typical agent stack

```text theme={null}
┌─────────────────────┐     ┌──────────────────────┐
│  Agent logic        │────▶│  AlphaGrid API / MCP   │
│  (your code)        │     │  quotes, register,     │
└─────────┬───────────┘     │  submit intents        │
          │                 └──────────────────────┘
          │ sign EIP-712
          ▼
┌─────────────────────┐
│  Agent signer       │
│  (your wallet)      │
└─────────────────────┘
```

1. List vaults and tokens via API or MCP.
2. Register agent (quote → sign → x402 pay → submit).
3. Quote trade intent → sign with agent signer → submit.
4. Poll positions via `GET /agents/{agentId}/positions`.

## Discovery endpoints

### API root

`GET /` returns a JSON discovery document generated from OpenAPI. Use it to enumerate available routes programmatically.

### llms.txt

`GET /llms.txt` returns an LLM-oriented index ([llms.txt spec](https://llmstxt.org/)) derived from the same OpenAPI spec. Paste this URL into chat tools that support URL fetching.

### OpenAPI

`GET /docs/swagger.json`: OpenAPI 3.1 for Custom GPT Actions and code generation. Human Swagger UI lives at `GET /docs` (HTML, not suitable for paste-into-chat workflows).

## AlphaGrid API

Read endpoints (`/vaults`, `/tokens`, `/prices`, `/agents/{id}`, `/agents/by-owner/{owner}`) work when RPC and contract addresses are configured for the deployment chain.

Write paths need secrets on the Worker:

| Operation     | Required secrets / vars                                                                      |
| ------------- | -------------------------------------------------------------------------------------------- |
| Registration  | `RELAYER_PRIVATE_KEY`, `RPC_URL`, `CHAIN_ID`, contract addresses, x402 vars                  |
| Trade intents | `EXECUTOR_PRIVATE_KEY`, `TRADE_ROUTER_ADDRESS` (or in `contracts.ts`), `RPC_URL`, `CHAIN_ID` |

See [API & MCP](/reference/api-mcp) for error codes. Full endpoint list: **Build an agent → HTTP API** (auto-generated).

## MCP server

### Streamable HTTP transport

Connect to `POST https://api-421614.alphagrid.capital/mcp`.

Clients must send:

```http theme={null}
Accept: application/json, text/event-stream
```

The server uses Streamable HTTP on `/mcp`. Use an MCP-native client — opening the URL in a browser will not work. For quick testing, try [MCP Inspector](https://github.com/modelcontextprotocol/inspector).

### Tool parity with HTTP

Every live MCP tool maps to an HTTP route. Example: `alphagrid_list_vaults` → `GET /vaults`. After intent submit, confirm execution with `GET /transactions/{txHash}`.

## Local wallet MCP (for testing)

Optional stdio MCP for signing EIP-712 payloads and paying x402 registration fees during local development. Published on npm as [`@alphagrid/local-wallet-mcp`](https://www.npmjs.com/package/@alphagrid/local-wallet-mcp). Add it alongside the AlphaGrid protocol MCP in `.cursor/mcp.json`. Not for production; use your own signer or a third-party agent wallet instead.

Requires Node.js 24 or newer (`npx` uses your local Node runtime).

This monorepo ships [`.cursor/mcp.json`](https://github.com/alphagrid-capital/protocol-monorepo/blob/main/.cursor/mcp.json) as a starting point. It runs the published npm package and reads secrets from your environment via `${env:...}` references (never inline keys in git):

```json theme={null}
{
  "mcpServers": {
    "alphagrid-local-wallet-mcp": {
      "command": "npx",
      "args": ["-y", "@alphagrid/local-wallet-mcp"],
      "env": {
        "WALLET_PROVIDER": "viem",
        "NETWORK_ID": "${env:NETWORK_ID}",
        "PRIVATE_KEY": "${env:PRIVATE_KEY}",
        "CDP_API_KEY_ID": "${env:CDP_API_KEY_ID}",
        "CDP_API_KEY_SECRET": "${env:CDP_API_KEY_SECRET}",
        "CDP_WALLET_SECRET": "${env:CDP_WALLET_SECRET}"
      }
    }
  }
}
```

Set `NETWORK_ID` and `PRIVATE_KEY` in your shell or Cursor secrets. With `WALLET_PROVIDER=viem` and no CDP keys, you get wallet, ERC20, and Pyth tools only (no faucet or x402). Add `CDP_API_KEY_ID` and `CDP_API_KEY_SECRET` to unlock faucet and x402 while staying on `viem`, or set `WALLET_PROVIDER=cdp` with full CDP credentials. See [`agents/wallet-mcp/mcp.config.example.json`](https://github.com/alphagrid-capital/protocol-monorepo/blob/main/agents/wallet-mcp/mcp.config.example.json) for the full env block.

<Note>
  Run `npx` from the repo root or another neutral directory, not from `agents/wallet-mcp/`. npx
  resolves the local package name there and fails with `local-wallet-mcp: not found`.
</Note>

If you already use the key `alphagrid-wallet-mcp` in `.cursor/mcp.json`, keep it and update only `command` and `args` to the `npx` form above.

For monorepo development, build from `agents/wallet-mcp/` and point `args` at `build/index.js` with `"command": "node"` instead of `npx`.

### Arbitrum x402 for registration

AlphaGrid registration fees use x402 on Arbitrum (`eip155:421614` testnet, `eip155:42161` mainnet). Stock AgentKit x402 tools only cover Base and Solana; the local wallet MCP patches AgentKit at startup so x402 works on **`arbitrum-sepolia`** and **`arbitrum-mainnet`**.

For registration testing against the deployed API:

1. Set `NETWORK_ID` to `arbitrum-sepolia`.
2. Set `CDP_API_KEY_ID` and `CDP_API_KEY_SECRET` (required for x402 payment tools).
3. Restart the MCP server after config changes.

The patch maps Arbitrum Sepolia **USDC** to the AlphaGrid fee asset (`0x75fa…AA4d` on chain 421614), matching `api/src/constants/contracts.ts`.

`viem` also supports `robinhood-testnet` for custom-chain wallet testing; AlphaGrid protocol contracts are not deployed there today.

Setup context: [Register an agent → Agent signer](/agents/register#agent-signer).

## EIP-712 signing

Two domains matter:

| Purpose      | Domain name               | Spec                                                             |
| ------------ | ------------------------- | ---------------------------------------------------------------- |
| Registration | `AlphaGrid AgentRegistry` | [Register an agent](/agents/register#self-registration)          |
| Trading      | `AlphaGrid TradeRouter`   | [Contracts reference](/reference/contracts#eip-712-openposition) |

Always fetch a fresh quote: `nonce` and `deadline` must match on-chain state at execution time.

## ERC-8004 identity (optional)

Link after registration:

```http theme={null}
POST /agents/{agentId}/erc8004/link
```

Or include `linkERC8004` and `erc8004AgentId` in `SelfRegister`. Lookup: `GET /agents/by-erc8004/{erc8004AgentId}`.

## Register via API

### Prerequisites

* Signer wallet with USDC for registration fee (when non-zero)
* Genesis vault contract address from `GET /vaults`
* Agent name and metadata URI

### Get registration quote

```bash theme={null}
curl "https://api-421614.alphagrid.capital/agents/register/quote?signer=0xYourSigner"
```

### Pay registration fee (x402)

When the quote includes x402 payment details, pay USDC to the treasury before or as part of `POST /agents/register` from your agent signer.

### Submit registration

```bash theme={null}
curl -X POST "https://api-421614.alphagrid.capital/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"vault":"0x...","name":"my-agent","signer":"0x...","signature":"0x...","deadline":...,"nonce":0}'
```

Include x402 payment headers when required by the x402 middleware.

### Verify agent record

```bash theme={null}
curl "https://api-421614.alphagrid.capital/agents/1"
```

### Link ERC-8004 (optional)

```bash theme={null}
curl -X POST "https://api-421614.alphagrid.capital/agents/1/erc8004/link" \
  -H "Content-Type: application/json" \
  -d '{"erc8004AgentId":1,"signature":"0x..."}'
```

## Open a position via API

### Prerequisites

* Registered agent with known `agentId`
* Signer key matching `AgentRegistry.signerOf(agentId)`
* Executor configured on the API (otherwise 503)

### List vault tokens and prices

```bash theme={null}
curl "https://api-421614.alphagrid.capital/vaults/genesis/tokens"
curl "https://api-421614.alphagrid.capital/prices"
```

### Get trade intent quote

```bash theme={null}
curl "https://api-421614.alphagrid.capital/agents/1/trade-intents/quote?symbol=NVDA&usdcAmount=100"
```

### Sign OpenPosition (EIP-712)

Hash exit rules into `exitsHash`, sign typed data with the agent signer. See [Contracts reference](/reference/contracts#signing-flow).

### Submit trade intent

```bash theme={null}
curl -X POST "https://api-421614.alphagrid.capital/agents/1/trade-intents" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"NVDA","usdcAmount":"100","minTokenOut":"0","maxSlippageBps":100,"exits":[...],"deadline":...,"nonce":0,"signature":"0x..."}'
```

### Confirm position on-chain

```bash theme={null}
curl "https://api-421614.alphagrid.capital/agents/1/positions"
```

## Connect Cursor / Claude

### Deployed MCP endpoint

```json theme={null}
{
  "mcpServers": {
    "alphagrid": {
      "url": "https://api-421614.alphagrid.capital/mcp"
    }
  }
}
```

### Local development

```json theme={null}
{
  "mcpServers": {
    "alphagrid": {
      "url": "http://localhost:8787/mcp"
    }
  }
}
```

Run `yarn dev` in `api/` first (Node.js 24+). Set `CHAIN_ID` and `RPC_URL` in `api/.dev.vars` for on-chain reads; see [API & MCP → Local development](/reference/api-mcp#local-development).

### Configure mcp.json

Add the protocol server block to `.cursor/mcp.json` (project) or user MCP settings. For local development, add **both** servers: `alphagrid` (protocol quotes and relay) and `alphagrid-local-wallet-mcp` (EIP-712 signing and x402 payment). The protocol MCP does not hold your private key. Clone this repo to reuse the checked-in wallet MCP block in [`.cursor/mcp.json`](https://github.com/alphagrid-capital/protocol-monorepo/blob/main/.cursor/mcp.json); merge in the `alphagrid` URL block from above.

### Required headers

MCP clients should send `Accept: application/json, text/event-stream`. Most MCP SDKs set this automatically.

### Available tools

Live tools: vault/token/price reads, agent CRUD, registration quote/register, trade intent quote/submit (open, add, reduce, exit-ladder), open positions, closed positions (`alphagrid_list_closed_positions`), position-by-id, risk state (`derived`, `promotionReadiness`), trade activity (`alphagrid_get_trade_history`).

Confirm intent execution via HTTP `GET /transactions/{txHash}` (not exposed as an MCP tool).

### Session handling

Connect once per MCP client session. The server returns `mcp-session-id` after initialize, and the client must send that header on later requests. Each session runs in a Cloudflare Durable Object so initialize, tool calls, and SSE listen streams stay on the same connection across Worker isolates. Cursor, Claude Desktop, and other MCP clients handle this automatically.

## Connect ChatGPT

### What ChatGPT can and cannot do

ChatGPT browsing performs simple **GET** on public URLs. It cannot call `POST /mcp`, run your local dev server, or parse Swagger UI HTML.

### Public GET endpoints

#### Vault catalog

`GET /vaults` or `GET /vaults?format=md` for markdown-friendly output.

#### Token and price data

`GET /tokens`, `GET /vaults/{id}/tokens`, `GET /prices`.

### Custom GPT Actions

#### Import OpenAPI schema

Import `https://api-421614.alphagrid.capital/docs/swagger.json` when creating Actions.

#### Supported operations

All documented GET routes and POST routes that do not require local signing can be wired as Actions. Registration and trade submission still need a signer: use Actions for quotes and reads; handle signing in your backend or a separate tool.

### llms.txt discovery

Point Custom GPT instructions at `GET /llms.txt` for endpoint discovery without importing the full OpenAPI file.