gatepay-local-mcp

gatepay-local-mcp is a local stdio MCP server for calling X402 payment-protected HTTP endpoints. It provides a suite of MCP tools to handle the complete X402 payment workflow, from placing orders to signing payments and submitting them to merchants.

Features

• 7 MCP Tools covering order placement, signature flows, quick wallet / Gate Pay auth, and centralized payment retries
• Built-in X402 payment flow under src/x402/
• Multiple signing modes: local_private_key, quick_wallet, plugin_wallet
• Multi-chain support: EVM (Ethereum, Base, Polygon, etc.) and Solana
• Works with Cursor, Claude Desktop, and other MCP clients
• Auto-selects the first ready signing mode if not specified
• Gate Pay centralized payment (sign_mode: centralized_payment) and x402_centralized_payment helper for merchant-side settlement

Available Tools

1. x402_place_order

Send an HTTP request and return complete response information including headers, body, and the original request details.

Use case: Initial request to a payment-protected endpoint that returns 402 Payment Required.

Parameters:

{
  url: string;              // Target URL (required)
  method?: string;          // HTTP method: GET, POST, PUT, PATCH (default: POST)
  body?: string;            // JSON string request body (optional)
  sign_mode?: string;       // Signing mode: local_private_key, quick_wallet, plugin_wallet (auto-select if omitted)
  wallet_login_provider?: string; // OAuth provider: google, gate (default: gate)
}

Returns: Complete response with status code, headers (including PAYMENT-REQUIRED), body, and original request details.

---

2. x402_sign_payment

Parse X402 payment requirements, create a signed payment authorization, and submit the payment to complete a 402-protected request (all-in-one workflow).

Use case: Single-step payment flow - parse, sign, and submit in one call.

Parameters:

{
  url: string;                    // Target URL (required)
  method?: string;                // HTTP method (default: POST)
  body?: string;                  // JSON request body (optional)
  payment_required_header?: string; // Base64-encoded PAYMENT-REQUIRED header
  response_body?: string;         // Response body from 402 response (alternative to header)
  sign_mode?: string;             // Signing mode (auto-select if omitted)
  wallet_login_provider?: string; // OAuth provider (default: gate)
}

Returns: Final response from the merchant after successful payment.

---

3. x402_create_signature

Parse X402 payment requirements and create a signed payment authorization.

Use case: Two-step workflow - create signature first, then submit separately.

Parameters:

{
  payment_required_header?: string; // Base64-encoded PAYMENT-REQUIRED header
  response_body?: string;         // Response body from 402 response (alternative to header)
  sign_mode?: string;             // Signing mode (auto-select if omitted)
  wallet_login_provider?: string; // OAuth provider (default: gate)
}

Returns: Payment payload and base64-encoded PAYMENT-SIGNATURE header value.

---

4. x402_submit_payment

Submit a signed payment to complete a 402-protected request.

Use case: Second step of two-step workflow - submit the signature created by x402_create_signature.

Parameters:

{
  url: string;              // Target URL (required)
  method?: string;          // HTTP method (default: POST)
  body?: string;            // JSON request body (optional)
  payment_signature: string; // Base64-encoded PAYMENT-SIGNATURE from x402_create_signature (required)
}

Returns: Final response from the merchant.

---

5. x402_quick_wallet_auth

Pre-authorize with Quick Wallet using device-flow OAuth (Google or Gate account).

Use case: When using sign_mode: quick_wallet, run this first to complete the device-flow login before making payment requests.

Parameters:

{
  wallet_login_provider?: string; // OAuth provider: google, gate (default: gate)
}

Returns: Authorization status and wallet addresses (EVM and Solana).

---

6. x402_gate_pay_auth

Complete the Gate Pay OAuth device flow (browser authorize URL + localhost callback + remote token exchange) and cache the resulting access token/UID for centralized payments.

Use case: Required before calling x402_submit_payment with sign_mode: centralized_payment or when preparing to use x402_centralized_payment.

Parameters: None

Returns: Current authorization status with masked Gate Pay UID and access token indicators.

---

7. x402_centralized_payment

Parse the Base64-encoded PAYMENT-REQUIRED header and complete the Gate Pay centralized payment flow without submitting a PAYMENT-SIGNATURE.

Use case: When a merchant expects Gate Pay centralized settlement (e.g., OTA or off-chain marketplace) and you prefer an all-in-one helper instead of crafting PAYMENT-SIGNATURE.

Parameters:

{
  payment_required_header: string; // Base64-encoded PAYMENT-REQUIRED header (required)
}

Returns: Payment confirmation including prepayId, merchantTradeNo, currency, amount, and the raw API response.

---

Workflow Examples

Single-Step Workflow (Recommended)

1. x402_place_order         → Get payment requirements
2. x402_sign_payment        → Sign and submit payment (all-in-one)

Two-Step Workflow (Advanced)

1. x402_place_order         → Get payment requirements
2. x402_create_signature    → Create signed payment
3. x402_submit_payment      → Submit signed payment

Quick Wallet Pre-Auth

1. x402_quick_wallet_auth   → Authorize with Google/Gate
2. x402_place_order         → Get payment requirements
3. x402_sign_payment        → Sign and submit (using quick_wallet)

Centralized Payment (Gate Pay)

1. x402_gate_pay_auth       → Browser OAuth + token exchange (repeat when token expires)
2. x402_place_order         → Receive PAYMENT-REQUIRED header that encodes Gate Pay order info
3. x402_submit_payment      → Use payment_signature + sign_mode: "centralized_payment" to call the merchant with Authorization: Bearer
   或
3. x402_centralized_payment → Pass payment_required_header directly for all-in-one centralized settlement

Signing Modes

The server supports three automatic signing modes plus a dedicated Gate Pay centralized mode:

sign_mode	Status	Networks / Scope	Description
local_private_key	Ready when EVM_PRIVATE_KEY / SVM_PRIVATE_KEY set	EVM, Solana	Signs locally with your private keys (no external dependencies)
quick_wallet	Ready after OAuth login	EVM, Solana	Custodial MCP wallet with device-flow login (Google/Gate account)
plugin_wallet	Ready when PLUGIN_WALLET_TOKEN set	EVM, Solana	Browser extension wallet (e.g., Gate Wallet) via MCP bridge
centralized_payment	Ready after x402_gate_pay_auth completes	Gate Pay	Adds Authorization: Bearer <Gate Pay access_token> when calling x402_submit_payment or use x402_centralized_payment

Priority Order (auto-selection applies to the first three rows when sign_mode is omitted):

1. plugin_wallet (priority: 30) - if token configured
2. quick_wallet (priority: 20) - if MCP endpoint configured
3. local_private_key (priority: 10) - if private keys configured

The server automatically selects the highest-priority ready mode.

Network Support

• EVM Networks: Ethereum, Base, Polygon, Arbitrum One, GateChain, GateLayer
• Solana Networks: Solana Mainnet, Solana Devnet

Quick Start

1. Local Private Key Mode (EVM + Solana)

This is the simplest setup for local signing with your own private keys:

{
  "mcpServers": {
    "gatepay-mcp": {
      "command": "npx",
      "args": ["-y", "gatepay-local-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "your-evm-private-key-hex-with-or-without-0x-prefix",
        "SVM_PRIVATE_KEY": "your-solana-private-key-base58-optional"
      }
    }
  }
}

• Set EVM_PRIVATE_KEY for EVM network payments (Ethereum, Base, Polygon, etc.)
• Set SVM_PRIVATE_KEY for Solana network payments (optional)
• Put this into your MCP config such as ~/.cursor/mcp.json, then restart or reload MCP

2. Quick Wallet Mode (Custodial)

Remote wallet signing with device-flow OAuth (Google or Gate account):

{
  "mcpServers": {
    "gatepay-mcp": {
      "command": "npx",
      "args": ["-y", "gatepay-local-mcp"],
      "env": {
        "QUICK_WALLET_MCP_URL": "https://walletmcp.gate.com/mcp",
        "QUICK_WALLET_API_KEY": "your-api-key-optional"
      }
    }
  }
}

• First payment will trigger device-flow login (opens browser)
• Token is persisted at ~/.gate-pay/auth.json
• Use x402_quick_wallet_auth tool to pre-authorize

3. Plugin Wallet Mode (Browser Extension)

Sign with browser extension wallet (e.g., Gate Wallet):

{
  "mcpServers": {
    "gatepay-mcp": {
      "command": "npx",
      "args": ["-y", "gatepay-local-mcp"],
      "env": {
        "PLUGIN_WALLET_TOKEN": "your-plugin-wallet-mcp-token"
      }
    }
  }
}

• Get the token from your browser extension wallet
• Requires the wallet extension to be installed and running
• User confirms transactions in the browser extension

4. Gate Pay Centralized Payment (Browser OAuth)

Use this when merchants expect Gate Pay centralized settlement instead of user-owned signatures.

{
  "mcpServers": {
    "gatepay-mcp": {
      "command": "npx",
      "args": ["-y", "gatepay-local-mcp"],
      "env": {
        "GATE_PAY_OAUTH_CLIENT_ID": "your-gate-pay-client-id",
        "GATE_PAY_OAUTH_CLIENT_SECRET": "your-gate-pay-client-secret",
        "GATE_PAY_OAUTH_BACKEND_ORIGIN": "https://www.gate.com/apiw/v2/mcp/oauth",
        "GATE_PAY_ACCOUNT_AUTHORIZE_ORIGIN": "https://gate.com",
        "GATE_PAY_OAUTH_CALLBACK_PORT": "18473",
        "GATE_PAY_CENTRALIZED_PAYMENT_URL": "https://api.gateio.ws/api/v4/pay/ai/order/pay",
        "GATE_PAY_CLIENT_ID": "your-gate-pay-client-id"
      }
    }
  }
}

• Run x402_gate_pay_auth once per token lifecycle; it opens the Gate consent page and exchanges the code automatically.
• Use x402_submit_payment with sign_mode: "centralized_payment" after you create a PAYMENT-SIGNATURE, or
• Call x402_centralized_payment directly with the Base64 PAYMENT-REQUIRED header when you prefer a single-step helper.

Cursor / Claude Desktop with plugin wallet

If you want to use a browser extension wallet (like Gate Wallet) for signing, configure the plugin wallet mode:

{
  "mcpServers": {
    "gatepay-mcp": {
      "command": "npx",
      "args": ["-y", "gatepay-local-mcp"],
      "env": {
        "PLUGIN_WALLET_SERVER_URL": "https://your-plugin-wallet-server.com",
        "PLUGIN_WALLET_TOKEN": "your-token-from-browser-wallet"
      }
    }
  }
}

Before using plugin wallet mode:

1. Install a compatible browser extension wallet (e.g., Gate Wallet)
2. Open the wallet extension in your browser and obtain the connection token
3. Configure PLUGIN_WALLET_SERVER_URL and PLUGIN_WALLET_TOKEN in your MCP config
4. The wallet extension must be active in your browser when making x402 requests

Environment Variables

The server loads .env from the repository or package root at startup.

Signing Mode Configuration

Variable	Mode	Description
EVM_PRIVATE_KEY	local_private_key	Local EVM private key; hex with or without 0x prefix
SVM_PRIVATE_KEY	local_private_key	Local Solana private key; base58 encoded (optional)
QUICK_WALLET_MCP_URL	quick_wallet	MCP wallet endpoint URL (default: https://walletmcp.gate.com/mcp)
QUICK_WALLET_API_KEY	quick_wallet	API key for MCP wallet service (optional)
PLUGIN_WALLET_TOKEN	plugin_wallet	MCP token from browser extension wallet

Gate Pay Centralized Payment

Variable	Description
GATE_PAY_OAUTH_CLIENT_ID	Gate Pay OAuth client id used for device authorization and token exchange
GATE_PAY_OAUTH_CLIENT_SECRET	Client secret required when exchanging the authorization code for an access token
GATE_PAY_OAUTH_BACKEND_ORIGIN	Base URL for the OAuth backend that hosts the token/refresh endpoints
GATE_PAY_ACCOUNT_AUTHORIZE_ORIGIN	Domain that serves the Gate Pay authorization page (opens in the browser)
GATE_PAY_OAUTH_CALLBACK_PORT	Local port used to receive the OAuth redirect (set to 0 for a random port if needed)
GATE_PAY_OAUTH_SCOPE	OAuth scope requested during device/login flow
GATE_PAY_OAUTH_AUTHORIZE_USER_AGENT	Custom User-Agent for the authorization preflight (defaults to gateio/web)
GATE_PAY_CENTRALIZED_PAYMENT_URL	HTTPS endpoint for submitting centralized payments via Gate Pay
GATE_PAY_CLIENT_ID	Merchant client id embedded in centralized payment payloads
GATE_PAY_OAUTH_TOKEN_BASE_URL	Optional: origin used to derive default token and refresh endpoints
GATE_PAY_OAUTH_TOKEN_URL	Optional: explicit token endpoint path override
GATE_PAY_OAUTH_REFRESH_URL	Optional: explicit refresh endpoint path override

Test and Script Variables

Variable	Used By	Default	Description
RESOURCE_SERVER_URL	test/privateKey.ts	http://localhost:8080	Base URL for the local private-key flow test
ENDPOINT_PATH	test/privateKey.ts	/flight/order	Endpoint path appended to RESOURCE_SERVER_URL
GATEPAY_MCP_TEST_TIMEOUT_MS	test/mcp-x402-request-tool.ts	180000	Timeout for the MCP tool integration test

Usage Examples

Example 1: Single-Step Payment (Recommended)

// Step 1: Place order to get payment requirements
{
  "tool": "x402_place_order",
  "arguments": {
    "url": "https://api.example.com/order",
    "method": "POST",
    "body": "{\"flightId\":\"FL001\",\"uid\":\"100\"}"
  }
}

// Step 2: If 402 response, sign and submit payment
{
  "tool": "x402_sign_payment",
  "arguments": {
    "url": "https://api.example.com/order",
    "method": "POST",
    "body": "{\"flightId\":\"FL001\",\"uid\":\"100\"}",
    "payment_required_header": "<base64-from-place_order>",
    "sign_mode": "quick_wallet"
  }
}

Example 2: Two-Step Payment (Advanced)

// Create signature first
{
  "tool": "x402_create_signature",
  "arguments": {
    "payment_required_header": "<base64>",
    "sign_mode": "local_private_key"
  }
}

// Then submit separately
{
  "tool": "x402_submit_payment",
  "arguments": {
    "url": "https://api.example.com/order",
    "payment_signature": "<base64-from-create_signature>"
  }
}

Example 3: Quick Wallet with Pre-Auth

// Pre-authorize (opens browser for OAuth)
{
  "tool": "x402_quick_wallet_auth",
  "arguments": {
    "wallet_login_provider": "gate"
  }
}

Example 4: Gate Pay Centralized Payment

// Step 1: Run OAuth (opens Gate authorize page)
{ "tool": "x402_gate_pay_auth", "arguments": {} }

// Step 2a: Use centralized helper
{
  "tool": "x402_centralized_payment",
  "arguments": {
    "payment_required_header": "<base64-from-place_order>"
  }
}

// Step 2b: Or submit with sign_mode: centralized_payment
{
  "tool": "x402_submit_payment",
  "arguments": {
    "url": "https://api.example.com/order",
    "method": "POST",
    "payment_signature": "<base64-from-create_signature>",
    "sign_mode": "centralized_payment"
  }
}

Agent Skill

• skills/SKILL.md contains the gatepay-x402 skill manifest and prompts so MCP-aware IDEs (Cursor, Claude Desktop, Codex CLI, etc.) know how to call every tool exposed by this server.
• skills/gatepay-x402.md (mirrored at docs/gatepay-x402.md) is a natural-language installation guide. Share that link with your AI host for a “one-click” experience: the host can follow the steps to download gatepay-local-mcp, register it in mcpServers, and copy the gatepay-x402 skill into its skills directory automatically.

Tool names and arguments always match each tool’s MCP inputSchema on the server you connect to; check your client’s tool list if you ship a trimmed build.

Development

# install dependencies
npm install

# build TypeScript output into dist/
npm run build

# start the MCP server from source
npm run dev

# run the built entrypoint through the package start script
npm start

# run unit tests
npm run test:unit

# run the local private key flow test
npm run test:privateKey

# run the MCP tool integration test
npm run test:mcp-tool

Integration test notes

npm run test:mcp-tool starts dist/src/index.js and calls x402_request against the configured remote wallet flow. The test requires proper wallet credentials to be configured.

npm run build
npm run test:mcp-tool

If you already logged in before, the saved token in ~/.gate-pay/auth.json will be reused. Otherwise the quick wallet flow may require interactive device login. You can increase the timeout with GATEPAY_MCP_TEST_TIMEOUT_MS.

License

MIT