### Install Dependencies and Start Server

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Install project dependencies using Bun, copy and configure environment variables, and start the server. Ensure all minimum required environment variables are set.

```bash
# Install dependencies
bun install

# Copy and edit configuration
cp .env.example .env

# Minimum required variables:
# CHAIN=mainnet                          # anvil | sepolia | mainnet
# CHAIN_ID=1
# RPC_URL=https://mainnet.infura.io/v3/<KEY>,https://eth.llamarpc.com  # fallback list
# TOKEN_ADDRESS=0xaF1E52927d724Fd34773Bd53adA57f4C2B742069
# MINT_DELEGATE_ADDRESS=0x4206936776996fD5DFd13dB2D69b38a5FA23C848
# RELAYER_PRIVATE_KEY=0x<pre-funded-relayer-wallet-private-key>
# RELAYER_MAX_FEE_GWEI=4.2069           # required, no default — pick per chain

# Production-recommended additions:
# MCP_ALLOWED_IP_CIDRS=160.79.104.0/21  # anthropic outbound CIDR
# RELAYER_MIN_BALANCE_ETH=0.05          # /health returns 503 below this ETH

# Start the server (listens on 127.0.0.1:42069 by default)
bun --hot --env-file=.env run src/server.ts
```

--------------------------------

### Start Backend Server

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/DEPLOY.md

Starts the Dogeshit MCP backend server. Ensure you copy the example environment file, fill in the required variables, and set the BASE_URL and FRONTEND_URL.

```sh
cd backend
cp .env.example .env
# fill in: TOKEN_ADDRESS, MINT_DELEGATE_ADDRESS, RELAYER_PRIVATE_KEY,
#          BASE_URL=https://api.example.com, FRONTEND_URL=https://app.example.com
bun run src/server.ts
# server listening on 127.0.0.1:42069
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Installs project dependencies using the Bun package manager. Ensure Bun is installed and an RPC URL is available.

```sh
bun install
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Copies the example environment file and instructs on editing required variables such as chain details, contract addresses, and relayer credentials. Essential for the backend to boot correctly.

```sh
cp .env.example .env
# Edit .env (required, process won't boot without these):
#   CHAIN, RPC_URL                        — your chain + RPC endpoint(s)
#   TOKEN_ADDRESS, MINT_DELEGATE_ADDRESS  — deployed contract addresses
#   RELAYER_PRIVATE_KEY                   — pre-funded wallet that signs mint txs
#   RELAYER_MAX_FEE_GWEI                  — gas cap (e.g. 4.2069 mainnet, 0.42069 L2)
# Strongly recommended for production:
#   MCP_ALLOWED_IP_CIDRS=160.79.104.0/21  — gate /mcp to claude.ai egress
#   RELAYER_MIN_BALANCE_ETH=0.05          — alert before relayer runs dry
```

--------------------------------

### Run the MCP Server Locally

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Starts the MCP backend server using Bun with hot-reloading and environment file loading. The server will be accessible on port 42069.

```sh
bun --hot --env-file=.env run src/server.ts        # backend on :42069
```

--------------------------------

### Mint Tokens with `token_mint` (Single Slot)

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Initiate a token minting transaction using the `token_mint` tool. This example shows minting a single slot, which yields 10,000,000 $SHIT and costs 0.00111 ETH. The operation is protected by a 60-second idempotency cache.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"token_mint","arguments":{"count":1}}}' | jq .result.content[0].text | jq -r | jq .
```

--------------------------------

### Get Token Information with token_info

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Returns global $SHIT token state including total supply, max supply, mint delegate, mint amounts, and fees. Immutable values are cached, while supply and mint counts require live RPC reads.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"token_info","arguments":{}}}' | jq .result.content[0].text | jq -r | jq .
```

--------------------------------

### Start Cloudflare Tunnel

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/DEPLOY.md

Runs the Cloudflare tunnel using the specified name. This command should be run in a separate terminal from the backend server.

```sh
cloudflared tunnel run dogeshit-mcp
```

--------------------------------

### Call Tool: Get Token Balance

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Use the `tools/call` method with the `token_balance` tool to retrieve the token balance for a given wallet address. Ensure your Authorization header is valid.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"token_balance","arguments":{}}}' | jq .result
```

--------------------------------

### Kubernetes Liveness Probe Configuration

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/DEPLOY.md

Example configuration for a Kubernetes liveness probe. This checks the health of the backend service by sending an HTTP GET request to the /health endpoint.

```yaml
httpGet: { path: /health, port: 42069 }
```

--------------------------------

### Get Token Balance with token_balance

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Reads the $SHIT ERC-20 balance for a given Ethereum address. Defaults to the caller's wallet if no address is provided. Validates the address format before RPC call.

```bash
# Caller's own balance (no argument)
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"token_balance","arguments":{}}}' | jq .result.content[0].text | jq -r | jq .
```

```bash
# Arbitrary address balance
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"token_balance","arguments":{"address":"0xaF1E52927d724Fd34773Bd53adA57f4C2B742069"}}}' | jq .result.content[0].text | jq -r | jq .
```

--------------------------------

### GET /health — Liveness and Readiness Probe

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

This endpoint performs liveness and readiness checks for the Dogeshit MCP backend. It verifies RPC reachability, SQLite connectivity, and the relayer's Ethereum balance. It returns a 200 OK status if all checks pass, and a 503 Service Unavailable status if any check fails. The results are cached for 5 seconds to optimize RPC usage and include relayer queue metrics.

```APIDOC
## GET /health — Liveness and Readiness Probe

### Description
Runs three parallel checks (RPC reachability, SQLite ping, relayer ETH balance) and returns `200` when all pass or `503` when any fail. Result is cached for 5 seconds to bound RPC cost. Includes relayer queue metrics as a monitoring sidecar.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if all checks passed.
- **checks** (object) - Details of the individual checks performed.
  - **rpc** (object) - Result of the RPC reachability check.
    - **ok** (boolean) - Status of the RPC check.
    - **detail** (object) - Additional details about the RPC check.
      - **block** (string) - The latest block number.
  - **sqlite** (object) - Result of the SQLite ping.
    - **ok** (boolean) - Status of the SQLite check.
  - **relayer_balance** (object) - Result of the relayer ETH balance check.
    - **ok** (boolean) - Status of the relayer balance check.
    - **detail** (object) - Additional details about the balance check.
      - **eth** (string) - Current balance of the relayer in ETH.
      - **threshold_eth** (number) - The minimum required balance in ETH.
- **metrics** (object) - Monitoring metrics for the relayer queue.
  - **queue** (object) - Queue metrics.
    - **in_flight** (number) - Number of tasks currently in flight.
    - **max** (number) - Maximum capacity of the queue.
    - **utilization_pct** (number) - Percentage of queue utilization.
    - **distinct_callers** (number) - Number of distinct callers.
    - **largest_caller** (number) - Size of the largest caller's queue.
    - **per_caller_max** (number) - Maximum queue size per caller.

#### Degraded Response (503)
- **ok** (boolean) - `false` when checks fail.
- **checks** (object) - Details of the individual checks performed, with `ok` set to `false` for failed checks.
- **metrics** (object) - Monitoring metrics for the relayer queue.
```

--------------------------------

### Batch Mint Tokens with `token_mint` (Multiple Slots)

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Mint multiple slots of tokens in a single transaction using the `token_mint` tool by specifying the `count` argument. This example demonstrates batch minting 3 slots, costing 0.00333 ETH. Note the wallet lifetime cap of 10 slots.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"token_mint","arguments":{"count":3}}}' | jq .result.content[0].text | jq -r | jq .
```

--------------------------------

### GET /api/config — Chain and Contract Configuration

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

This endpoint retrieves the current chain and contract configuration for the Dogeshit MCP backend. It returns immutable contract addresses, token constants fetched from the chain at startup, and the relayer's address. This information is crucial for the frontend consent UI and for operators to verify backend configuration.

```APIDOC
## GET /api/config — Chain and Contract Configuration

### Description
Returns immutable contract addresses, token constants (read and cached from chain at startup), and the relayer address. Used by the frontend consent UI and by operators to verify the backend is configured against the correct contracts.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the configuration was retrieved successfully.
- **chain** (string) - The name of the blockchain network (e.g., "homestead").
- **relayer** (string) - The Ethereum address of the relayer.
- **token** (string) - The Ethereum address of the $SHIT token contract.
- **mintDelegate** (string) - The Ethereum address of the MintDelegate contract.
- **feeWei** (string) - The base fee for minting transactions in Wei.
- **maxTotalMints** (string) - The maximum total number of mints allowed.
- **mintAmount** (string) - The amount of tokens to mint in a single transaction.
- **maxPerWallet** (string) - The maximum number of mints allowed per wallet.
- **baselineSupply** (string) - The initial supply of tokens.
- **maxSupply** (string) - The maximum total supply of tokens.
```

--------------------------------

### Run Full Integration Flow

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Execute the complete integration test flow, including OAuth, SIWE, 7702 self-tx, and MCP mint.

```bash
bun run tests/integration/full.ts
```

--------------------------------

### Verify Server Startup with Health Check

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Check the server's liveness and readiness by querying the /health endpoint. This endpoint performs checks for RPC reachability, SQLite ping, and relayer ETH balance, returning 200 on success and 503 on failure. The result is cached for 5 seconds.

```bash
curl http://127.0.0.1:42069/health
# {"ok":true,"checks":{"rpc":{"ok":true,"detail":{"block":"22345678"}},"sqlite":{"ok":true},"relayer_balance":{"ok":true,"detail":{"eth":"0.123456","threshold_eth":0.05}}},"metrics":{"queue":{"in_flight":0,"max":50,"utilization_pct":0,"distinct_callers":0,"largest_caller":0,"per_caller_max":0}}}
```

```bash
curl http://127.0.0.1:42069/health | jq .

# Healthy response (HTTP 200):
# {
#   "ok": true,
#   "checks": {
#     "rpc":              { "ok": true, "detail": { "block": "22345678" } },
#     "sqlite":           { "ok": true },
#     "relayer_balance":  { "ok": true, "detail": { "eth": "0.123456", "threshold_eth": 0.05 } }
#   },
#   "metrics": {
#     "queue": {
#       "in_flight": 3,
#       "max": 50,
#       "utilization_pct": 6,
#       "distinct_callers": 3,
#       "largest_caller": 1,
#       "per_caller_max": 1
#     }
#   }
# }

# Degraded response (HTTP 503) when relayer balance too low:
# {
#   "ok": false,
#   "checks": {
#     "rpc":             { "ok": true, "detail": { "block": "22345679" } },
#     "sqlite":          { "ok": true },
#     "relayer_balance": { "ok": false, "detail": { "eth": "0.010000", "threshold_eth": 0.05 } }
#   },
#   "metrics": { "queue": { "in_flight": 0, "max": 50, "utilization_pct": 0, ... } }
# }
```

--------------------------------

### List Available Tools with MCP

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Use the `tools/list` method to enumerate all available tools within the MCP. This is useful for discovering what operations can be performed.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools[].name'
```

--------------------------------

### MCP Architecture Overview

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Illustrates the flow of a mint request from a user through an AI agent to the MCP endpoint and finally to the relayer for on-chain execution. Highlights security measures like JWT subject matching the wallet and recipient enforcement.

```text
user → "mint me some shit" → claude.ai → MCP /mcp endpoint → relayer → mint()
                                           ↑                    ↑
                                    JWT.sub = wallet      tx.origin == relayer (gate)
                                    (issued via SIWE)     recipient = msg.sender (hardcoded)
```

--------------------------------

### Run Unit Tests with Bun

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Executes all unit tests for the project using the Bun test runner. These tests are auto-discovered and require no external dependencies, running in approximately 5 seconds.

```sh
bun test
```

--------------------------------

### MCP Tool: token_info

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Returns global $SHIT token state including total supply, max supply, mint delegate address, mint amount per slot, global mint counts, and per-slot ETH fee. Immutable values are cached, while total supply and mints require live RPC reads.

```APIDOC
## MCP Tool: `token_info`

### Description
Returns global $SHIT token state: current total supply, hardcapped max supply (420.69B), mint delegate address, per-slot mint amount, global mint counts, and the per-slot ETH fee. All immutable values (max supply, mint amount) come from the startup cache; only total supply and total mints require live RPC reads.

### Method
POST

### Endpoint
`/mcp`

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "token_info",
    "arguments": {}
  }
}
```

### Response Example (Success)
```json
{
  "token": "0xaF1E52927d724Fd34773Bd53adA57f4C2B742069",
  "mint_delegate": "0x4206936776996fD5DFd13dB2D69b38a5FA23C848",
  "total_supply": "214650000000000000000000000000",
  "total_supply_formatted": "214650000000.0",
  "max_supply": "420690000000000000000000000000",
  "max_supply_formatted": "420690000000.0",
  "mint_amount_per_slot": "10000000000000000000000000",
  "mint_amount_per_slot_formatted": "10000000.0",
  "max_total_mints": 21000,
  "max_per_wallet": 10,
  "total_mints": 14500,
  "mints_remaining": 6500,
  "fee_wei": "1110000000000000",
  "fee_eth": "0.00111"
}
```
```

--------------------------------

### Dynamic Client Registration for OAuth 2.1

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Register a new client application with the Authorization Server using dynamic client registration. This requires specifying the client name and redirect URIs.

```bash
# 2. Dynamic Client Registration (POST /register) — gated to MCP_ALLOWED_IP_CIDRS
curl -s -X POST http://127.0.0.1:42069/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"claude.ai","redirect_uris":["https://claude.ai/api/mcp/auth_callback"]}' | jq .
```

--------------------------------

### Initialize MCP Protocol

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Initiate communication with the MCP endpoint by negotiating the protocol version and receiving server capabilities. This request requires an Authorization header with a JWT.

```bash
# initialize — negotiate protocol version and receive server capabilities
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"claude.ai","version":"1.0"}}}' | jq .
```

--------------------------------

### Discover OAuth 2.1 AS Metadata

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Use curl to discover the Authorization Server's metadata, including endpoints and supported features. This is the first step in understanding the AS capabilities.

```bash
# 1. Discover AS metadata
curl -s http://127.0.0.1:42069/.well-known/oauth-authorization-server | jq .
```

--------------------------------

### List Available Tools

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Enumerates the tools available through the MCP.

```APIDOC
## POST /mcp

### Description
Lists all available tools that can be called via the MCP.

### Method
POST

### Endpoint
/mcp

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

### Response
#### Success Response (200)
Returns a list of tool names.

### Response Example
```json
{
  "result": {
    "tools": [
      "token_mint",
      "mint_quota_get",
      "token_balance",
      "token_info",
      "authorization_status"
    ]
  }
}
```
```

--------------------------------

### Run OAuth Integration Test

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Execute the integration test for the OAuth authentication service standalone.

```bash
bun run tests/integration/oauth.ts
```

--------------------------------

### Direct Public Bind with Bun

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/DEPLOY.md

Run the backend directly bound to all interfaces for public access without a reverse proxy. This method requires manual handling of TLS termination and DDoS mitigation.

```sh
HOST=0.0.0.0 bun run src/server.ts
```

--------------------------------

### Run MCP/OAuth Edge Cases Test

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Execute integration tests for MCP and OAuth edge cases. Requires MCP_DEV_AUTH=1 environment variable.

```bash
MCP_DEV_AUTH=1 bun run tests/integration/mcp-edges.ts
```

--------------------------------

### Check Authorization Status for Minting

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Before minting, use the `authorization_status` tool to check if the caller's EOA is delegated to the project's `MintDelegate`. This provides a `ready_to_mint` status and an `action_required` hint if delegation is needed.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"authorization_status","arguments":{}}}' | jq .result.content[0].text | jq -r | jq .
```

--------------------------------

### Fetch OAuth Session Details

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Retrieve session details from the Authorization Server, including client information, scopes, and SIWE message for wallet authentication. This is part of the authorization flow.

```bash
# 4. Frontend fetches session and builds SIWE message
curl -s http://127.0.0.1:42069/api/oauth/session/<session-id> | jq .
```

--------------------------------

### OAuth 2.1 Authorization Server

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

This section outlines the steps for interacting with the OAuth 2.1 Authorization Server, including discovering server metadata, dynamic client registration, and the authorization code flow.

```APIDOC
## Discover AS metadata
### Description
Fetches the OAuth 2.1 Authorization Server's metadata.
### Method
GET
### Endpoint
`/.well-known/oauth-authorization-server`
### Request Example
```bash
curl -s http://127.0.0.1:42069/.well-known/oauth-authorization-server | jq .
```
### Response Example
```json
{
  "issuer": "http://127.0.0.1:42069",
  "authorization_endpoint": "http://127.0.0.1:42069/authorize",
  "token_endpoint": "http://127.0.0.1:42069/token",
  "registration_endpoint": "http://127.0.0.1:42069/register",
  "jwks_uri": "http://127.0.0.1:42069/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["mcp:tools:read", "mcp:tools:write", "offline_access"]
}
```
```

```APIDOC
## Dynamic Client Registration
### Description
Registers a new client with the Authorization Server.
### Method
POST
### Endpoint
`/register`
### Parameters
#### Request Body
- **client_name** (string) - Required - The name of the client application.
- **redirect_uris** (array of strings) - Required - A list of valid redirect URIs for the client.
### Request Example
```bash
curl -s -X POST http://127.0.0.1:42069/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"claude.ai","redirect_uris":["https://claude.ai/api/mcp/auth_callback"]}' | jq .
```
### Response Example
```json
{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_id_issued_at": 1746652800,
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}
```
```

```APIDOC
## Authorization Redirect
### Description
Initiates the authorization flow by redirecting the user to the authorization endpoint.
### Method
GET
### Endpoint
`/authorize`
### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID obtained during registration.
- **redirect_uri** (string) - Required - The redirect URI registered for the client.
- **response_type** (string) - Required - Must be `code`.
- **code_challenge** (string) - Required - The code challenge generated for PKCE.
- **code_challenge_method** (string) - Required - Must be `S256`.
- **state** (string) - Required - A random string to maintain state.
- **scope** (string) - Optional - The requested scopes, space-separated.
### Response
- **302 Redirect** to the frontend authorization URL with a session ID.
```

```APIDOC
## Fetch Session
### Description
Retrieves session details, including the SIWE message, after an authorization redirect.
### Method
GET
### Endpoint
`/api/oauth/session/<session-id>`
### Parameters
#### Path Parameters
- **session-id** (string) - Required - The ID of the authorization session.
### Response Example
```json
{
  "id": "session-uuid",
  "client_name": "claude.ai",
  "scope": "mcp:tools:read mcp:tools:write",
  "wallet": null,
  "siwe": {
    "message": "127.0.0.1:42069 wants you to sign in with your Ethereum account:\n0x0000...\n\nURI: http://...\nVersion: 1\nChain ID: 1\nNonce: abc123\nIssued At: 2025-...",
    "nonce": "abc123"
  }
}
```
```

```APIDOC
## SIWE Verification
### Description
Verifies the SIWE signature and binds the wallet address to the session.
### Method
POST
### Endpoint
`/api/oauth/siwe-verify`
### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the authorization session.
- **message** (string) - Required - The SIWE message that was signed.
- **signature** (string) - Required - The signature of the SIWE message.
- **address** (string) - Required - The Ethereum wallet address.
### Request Example
```bash
curl -s -X POST http://127.0.0.1:42069/api/oauth/siwe-verify \
  -H "Content-Type: application/json" \
  -d '{"session_id":"session-uuid","message":"<siwe-message>","signature":"0xsig...","address":"0xUserWallet"}' | jq .
```
### Response Example
```json
{ "ok": true, "wallet": "0xUserWallet" }
```
```

```APIDOC
## Consent
### Description
Processes user consent and issues an authorization code.
### Method
POST
### Endpoint
`/api/oauth/consent`
### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the authorization session.
### Request Example
```bash
curl -s -X POST http://127.0.0.1:42069/api/oauth/consent \
  -H "Content-Type: application/json" \
  -d '{"session_id":"session-uuid"}' | jq .
```
### Response Example
```json
{ "redirect_to": "https://claude.ai/api/mcp/auth_callback?code=authcode123&state=random" }
```
```

```APIDOC
## Token Exchange
### Description
Exchanges an authorization code for access and refresh tokens.
### Method
POST
### Endpoint
`/token`
### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be `authorization_code`.
- **code** (string) - Required - The authorization code received.
- **client_id** (string) - Required - The client ID.
- **redirect_uri** (string) - Required - The redirect URI.
- **code_verifier** (string) - Required - The PKCE code verifier.
### Request Example
```bash
curl -s -X POST http://127.0.0.1:42069/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=authcode123&client_id=550e8400...&redirect_uri=https://...&code_verifier=<pkce-verifier>" | jq .
```
### Response Example
```json
{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "rt_abc123...",
  "scope": "mcp:tools:read mcp:tools:write"
}
```
```

```APIDOC
## Refresh Access Token
### Description
Refreshes an expired access token using a refresh token.
### Method
POST
### Endpoint
`/token`
### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be `refresh_token`.
- **refresh_token** (string) - Required - The refresh token.
### Request Example
```bash
curl -s -X POST http://127.0.0.1:42069/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=rt_abc123..." | jq .
```
### Response Example
```json
{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "rt_new..." }
```
```

--------------------------------

### Verify SIWE Signature and Bind Wallet

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Verify the SIWE signature provided by the user's wallet and bind the wallet address to the current session. This step authenticates the user's Ethereum identity.

```bash
# 5. After wallet signs SIWE message, POST signature to bind wallet to session
curl -s -X POST http://127.0.0.1:42069/api/oauth/siwe-verify \
  -H "Content-Type: application/json" \
  -d '{"session_id":"session-uuid","message":"<siwe-message>","signature":"0xsig...","address":"0xUserWallet"}' | jq .
```

--------------------------------

### Run Security Integration Test

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Execute the integration test for security aspects like CORS and state leakage.

```bash
bun run tests/integration/security.ts
```

--------------------------------

### Run MCP Protocol Layer Integration Test

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Execute the integration test focusing on the MCP protocol layer.

```bash
bun run tests/integration/mcp.ts
```

--------------------------------

### Verify Deployment with Curl

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/DEPLOY.md

Tests the deployment by making a request to the /health endpoint. A successful response indicates the server and tunnel are functioning correctly.

```sh
curl https://api.example.com/health
# → {"ok":true,"checks":{"rpc":...,"sqlite":...,"relayer_balance":...}}
```

--------------------------------

### MCP Tool: token_balance

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Reads the $SHIT ERC-20 balance for any Ethereum address. If no address is provided, it defaults to the caller's wallet. Address format is validated before the RPC call.

```APIDOC
## MCP Tool: `token_balance`

### Description
Reads $SHIT ERC-20 balance for any Ethereum address. Defaults to the caller's wallet if no address argument is provided. Validates the address format before making the RPC call.

### Method
POST

### Endpoint
`/mcp`

### Parameters
#### Arguments (in `params.arguments`)
- **address** (string) - Optional - The Ethereum address to query the balance for. Defaults to the caller's wallet if not provided.

### Request Example (Caller's own balance)
```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "token_balance",
    "arguments": {}
  }
}
```

### Request Example (Arbitrary address balance)
```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "token_balance",
    "arguments": {
      "address": "0xaF1E52927d724Fd34773Bd53adA57f4C2B742069"
    }
  }
}
```

### Response Example (Success)
```json
{
  "address": "0xUserWallet",
  "balance": "30000000000000000000000000",
  "balance_formatted": "30000000.0"
}
```

### Error Response Example
```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "internal error: invalid_input: invalid address"
  }
}
```
```

--------------------------------

### Retrieve Chain and Contract Configuration

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Fetch the current chain and contract configuration from the /api/config endpoint. This includes immutable contract addresses, token constants, and the relayer address, which are crucial for frontend consent UI and operator verification.

```bash
curl http://127.0.0.1:42069/api/config
# {"ok":true,"chain":"homestead","relayer":"0xRELAYER","token":"0xaF1E52927d724Fd34773Bd53adA57f4C2B742069","mintDelegate":"0x4206936776996fD5DFd13dB2D69b38a5FA23C848","feeWei":"1110000000000000","maxTotalMints":"21000","mintAmount":"10000000000000000000000000","maxPerWallet":"10","baselineSupply":"210690000000000000000000000000","maxSupply":"420690000000000000000000000000"}
```

```bash
curl -s http://127.0.0.1:42069/api/config | jq .

# {
#   "ok": true,
#   "chain": "homestead",
#   "relayer": "0xRelayerAddress",
#   "token": "0xaF1E52927d724Fd34773Bd53adA57f4C2B742069",
#   "mintDelegate": "0x4206936776996fD5DFd13dB2D69b38a5FA23C848",
#   "feeWei": "1110000000000000",

```

--------------------------------

### MCP Tool: mint_quota_get

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Reads the caller's per-wallet mint usage and global mint progress from the chain. It retrieves immutable constants from cache and live chain data for mint usage.

```APIDOC
## MCP Tool: `mint_quota_get`

### Description
Reads the caller's per-wallet mint usage and global mint progress from chain. Immutable constants (`maxPerWallet`, `mintAmount`) come from the startup cache at zero RPC cost; only `mintsOf(wallet)` and `totalMints()` require live chain reads.

### Method
POST

### Endpoint
`/mcp`

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "mint_quota_get",
    "arguments": {}
  }
}
```

### Response Example (Success)
```json
{
  "wallet": {
    "used": 3,
    "max": 10,
    "remaining": 7
  },
  "global": {
    "total_mints": 14500,
    "max_total_mints": 21000,
    "remaining": 6500
  },
  "mint_amount_per_slot": "10000000000000000000000000",
  "mint_amount_per_slot_formatted": "10000000.0"
}
```
```

--------------------------------

### Call a Specific Tool

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Allows for the invocation of a specific tool with provided arguments.

```APIDOC
## POST /mcp

### Description
Calls a specific tool with the given name and arguments.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tool to call.
- **arguments** (object) - Required - The arguments for the tool.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "token_balance",
    "arguments": {}
  }
}
```

### Response
#### Success Response (200)
Returns the result of the tool call.

### Response Example
```json
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"address\":\"0xUserWallet\",\"balance\":\"10000000000000000000000000\",\"balance_formatted\":\"10000000.0\"}"
      }
    ],
    "isError": false
  }
}
```
```

--------------------------------

### Token Mint

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Triggers the relayer to submit a mint transaction for $SHIT tokens.

```APIDOC
## MCP Tool: `token_mint`

### Description
Triggers the relayer to submit a `mint()` or `batchMint(count)` transaction on behalf of the caller's already-delegated EOA. Each slot mints 10,000,000 $SHIT and charges 0.00111 ETH from the caller's wallet. Wrapped in a 60-second idempotency cache keyed on `(wallet, count)` to absorb MCP-client transport retries without double-minting. Wallet lifetime cap is 10 slots.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **count** (integer) - Required - The number of slots to mint.

### Request Example (Mint 1 slot)
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "token_mint",
    "arguments": {
      "count": 1
    }
  }
}
```

### Response
#### Success Response (200)
Returns details of the minting operation.

### Response Example (Mint 1 slot)
```json
{
  "tx_hash": "0xabc123...",
  "minted_slots": 1,
  "minted_tokens": "10000000",
  "balance": "10000000000000000000000000",
  "balance_formatted": "10000000.0",
  "combined_activation": false
}
```

### Request Example (Batch mint 3 slots)
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "token_mint",
    "arguments": {
      "count": 3
    }
  }
}
```

### Response Example (Batch mint 3 slots)
```json
{
  "tx_hash": "0xdef456...",
  "minted_slots": 3,
  "minted_tokens": "30000000",
  "balance": "...",
  "balance_formatted": "...",
  "combined_activation": false
}
```

### Error Handling
- **Not delegated**: `{"jsonrpc":"2.0","id":5,"error":{ "code":-32603,"message":"internal error: not_delegated: Visit /oauth/authorize..." }}`
- **Wallet cap reached**: `{"jsonrpc":"2.0","id":5,"error":{ "code":-32603,"message":"internal error: wallet_cap_reached: wallet has only 0 mints remaining" }}`
- **Relayer queue full**: `{"jsonrpc":"2.0","id":5,"error":{ "code":-32603,"message":"internal error: queue_full: relayer in-flight 50/50 — retry later" }}`
```

--------------------------------

### Read Mint Quota Usage with mint_quota_get

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Reads the caller's per-wallet mint usage and global mint progress from the chain. Immutable constants are cached, while mint counts require live reads.

```bash
curl -s -X POST http://127.0.0.1:42069/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"mint_quota_get","arguments":{}}}' | jq .result.content[0].text | jq -r | jq .
```

--------------------------------

### Verify Server Health and Configuration

Source: https://github.com/dogeshitmeme/dogeshit-mcp/blob/main/README.md

Checks the liveness of the MCP server by querying its health endpoint, configuration, JWKS, and OAuth server details. Ensures the backend is running and accessible.

```sh
curl http://127.0.0.1:42069/health                 # liveness: rpc + sqlite + relayer ETH
curl http://127.0.0.1:42069/api/config             # chain + contract config
curl http://127.0.0.1:42069/jwks.json              # OAuth public keys
curl http://127.0.0.1:42069/.well-known/oauth-authorization-server
```

--------------------------------

### Create and Use Idempotency Cache

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Use this cache to deduplicate mutating MCP tool calls within a 60-second TTL. It prevents double-mints by returning the same Promise for identical keys within the cache window, caching both successes and failures. The cache has a hard cap of 10,000 entries with oldest-first eviction.

```typescript
import { createIdempotencyCache } from './src/mcp/idempotency.ts';

type MintResult = { tx_hash: string; minted_slots: number; balance: string };

// Create a cache with 60-second TTL
const mintCache = createIdempotencyCache<MintResult>(60_000);

// First call for a given key: fn() is executed and result cached
const { promise: p1, cached: c1 } = mintCache.dedupe(
  `mint:0xuserwallet:1`,
  async () => {
    // Actual on-chain mint — executed once
    return { tx_hash: '0xabc...', minted_slots: 1, balance: '10000000000000000000000000' };
  },
);
console.log(c1); // false — fresh call

// Retry within 60s: same Promise returned, fn() not called again
const { promise: p2, cached: c2 } = mintCache.dedupe(
  `mint:0xuserwallet:1`,
  async () => { /* never called */ return {} as MintResult; },
);
console.log(c2); // true — cache hit
console.log(p1 === p2); // true — same Promise object

// Both success and failure results are cached:
// If the first attempt returned receipt_timeout, the retry also gets receipt_timeout
// (preventing blind re-submission that could cause a double-mint).
const result = await p2;
// { tx_hash: '0xabc...', minted_slots: 1, balance: '10000000000000000000000000' }
```

--------------------------------

### Consent and Obtain Authorization Code

Source: https://context7.com/dogeshitmeme/dogeshit-mcp/llms.txt

Allow the user to consent to the requested scopes, after which the backend issues an authorization code and provides the redirect URL for the client application.

```bash
# 6. User consents — backend issues auth code and redirect URL
curl -s -X POST http://127.0.0.1:42069/api/oauth/consent \
  -H "Content-Type: application/json" \
  -d '{"session_id":"session-uuid"}' | jq .
```