xgate-server CLI

Query the xgate-server API for X402 services, ERC-8004 agents, and on-chain token transfers.

When to Use

• •"Search for services on xgate"
• •"Find agents that support MCP"
• •"Query xgate for resources"
• •"Get token transfers for address"
• •"Search xgate agents"
• •"List services on xgate-server"
• •"Set up xgate MCP"
• •"Connect xgate to Claude"
• •"How do I use x402 tools in Claude?"

MCP Setup

The xgate MCP lets Claude call x402 APIs directly with automatic micropayments. The human must authenticate — the agent cannot do this step.

Tell the human:

1. •Go to xgate.run and connect their wallet to generate an MCP connector URL
2. •Add to Claude — paste the URL into their Claude config:

Claude Code:

claude mcp add xgate --transport http https://xgate.run/user/<walletSlug>/mcp?token=<token>

Claude Desktop (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "xgate": {
      "url": "https://xgate.run/user/<walletSlug>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Once connected, the agent can:

• •Search resources: ask Claude to call xgate_search({ query: "weather" })
• •Add tools: xgate_add_resource({ url: "..." }) to add x402 APIs to the toolset
• •Use tools: call discovered APIs directly — payments settle automatically via server wallet

Important: If MCP tools aren't available, prompt the human to complete auth first. The agent cannot generate the connector URL — it requires wallet signing.

CLI Usage

Use the bundled CLI at plugins/xgate-server/scripts/xgate:

# Health check
./plugins/xgate-server/scripts/xgate health

# Search services
./plugins/xgate-server/scripts/xgate services -q "token" -n ethereum

# Get a specific service
./plugins/xgate-server/scripts/xgate service SERVICE_ID

# Search agents
./plugins/xgate-server/scripts/xgate agents -p MCP --min-score 0.8

# Query token transfers
./plugins/xgate-server/scripts/xgate transfers -c 8453 --totals

# Resource transfers
./plugins/xgate-server/scripts/xgate resource-transfers 0xADDRESS -c 1

Run ./plugins/xgate-server/scripts/xgate --help for full option reference.

API Base URL

https://api.xgate.run

Override via XGATE_URL environment variable.

Service Query Parameters

Agent Query Parameters

Transfer Query Parameters

Response Format

Services

{
  "query": {},
  "total": 42,
  "results": [
    {
      "id": "service_id",
      "resource": "0x...",
      "type": "http",
      "networks": ["ethereum"],
      "assets": ["USDC"],
      "score": 0.95
    }
  ],
  "diagnostics": { "latencyMs": 125 }
}

Agents

{
  "query": {},
  "total": 25,
  "results": [
    {
      "agentKey": "key",
      "agentId": "0x...",
      "name": "Agent Name",
      "protocols": ["MCP", "A2A"],
      "reputationScore": 0.95,
      "rankScore": 87.5
    }
  ]
}

Error Handling

Chain IDs

Tips

1. •Use --debug flag (or debug=true) to understand scoring/ranking
2. •Use pagination for large result sets (cursor-based for transfers, offset-based for services/agents)
3. •Check xgate health first if queries fail
4. •Pipe output through jq filters to extract specific fields