Developer Docs

Integrate ActionGate in minutes.

ActionGate returns deterministic JSON decisions for high-impact agent actions: risk score, simulation, and policy fit. Every paid response includes a signed usage receipt.

Machine discovery

https://api.actiongate.xyz/.well-known/agent.json

https://api.actiongate.xyz/.well-known/mcp/server-card.json

Reference

https://api.actiongate.xyz/docs/openapi-v1.yaml

Remote MCP: https://api.actiongate.xyz/mcp

MCP Registry namespace: xyz.actiongate.api/actiongate

Quickstart

npm install @actiongate/sdk

import { ActionGateClient } from "@actiongate/sdk";

const client = new ActionGateClient({ baseUrl: "https://api.actiongate.xyz" }); const result = await client.policyGate({ actor: { actor_id: "agent_ops_02" }, action: { action_type: "transfer", network: "base", asset_symbol: "USDC", amount: "150000" }, policy: { policy_id: "treasury_default_v1" } });

Install Surfaces

npm install @actiongate/sdk pip install actiongate-sdk

{ "mcpServers": { "actiongate": { "url": "https://api.actiongate.xyz/mcp" } } }

npm install -g actiongate-mcp

Client Configs

Use these exact snippets to connect ActionGate's remote MCP server in popular agent clients.

Claude Code

claude mcp add --transport http actiongate --scope project https://api.actiongate.xyz/mcp

VS Code

{ "servers": { "actiongate": { "type": "http", "url": "https://api.actiongate.xyz/mcp" } } }

Save that as .vscode/mcp.json.

Windsurf

{ "mcpServers": { "actiongate": { "serverUrl": "https://api.actiongate.xyz/mcp" } } }

Save that as ~/.codeium/windsurf/mcp_config.json.

Cursor

Save that as .cursor/mcp.json for a project-scoped setup or ~/.cursor/mcp.json for a global setup.

Free Tier

Every agent gets 16 total calls per day across tool-specific buckets: 6 risk score calls, 6 simulate calls, and 4 policy gate calls for free each day. No wallet, no signup — just connect and call. When you hit the limit you will receive a 402 response with x402 payment requirements. Follow the guide below to upgrade to paid calls.

How to Pay with x402

x402 is an open protocol for HTTP-native micropayments. When a tool call requires payment, ActionGate returns an HTTP 402 with payment requirements in the response headers. Your agent signs a USDC payment on Base and resends the request with the payment proof attached.

What you need

1. A wallet with USDC on Base (Coinbase Smart Wallet, MetaMask, or any EVM wallet). 2. The @x402/core package (or any x402-compatible client).

TypeScript example

import { paymentMiddleware } from "@x402/core";

// Wrap any HTTP client with x402 payment middleware. // When a 402 is received, the middleware automatically // signs a USDC payment and retries the request. const client = paymentMiddleware(fetch, { walletPrivateKey: process.env.WALLET_PRIVATE_KEY, network: "base", });

// Now calls that exceed the free tier will auto-pay: const res = await client("https://api.actiongate.xyz/v1/risk-score", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ actor: { actor_id: "my_agent" }, action: { action_type: "transfer", network: "base", asset_symbol: "USDC", amount: "5000" }, }), }); // Paid response includes a settlement receipt.

MCP with payment

For MCP clients that support x402 natively (like the actiongate-mcp stdio package), set PAYTO_ADDRESS and your wallet key in the environment. The MCP transport handles payment negotiation automatically.

{ "mcpServers": { "actiongate": { "command": "npx", "args": ["actiongate-mcp"], "env": { "PAYTO_ADDRESS": "0xYourWalletAddress", "WALLET_PRIVATE_KEY": "0xYourPrivateKey", "ACTIONGATE_BASE_URL": "https://api.actiongate.xyz" } } } }

Flow summary

1. Agent calls a tool (free tier or paid). 2. If free quota remains, the response is returned immediately — no payment needed. 3. If quota is exhausted, ActionGate returns HTTP 402 with x402 payment requirements. 4. Your x402 client signs a USDC micropayment on Base and resends the request with a PAYMENT-SIGNATURE header. 5. ActionGate verifies and settles the payment, then returns the tool result with a settlement receipt.

Launch Proof

ActionGate advertises paid discovery over x402 headers and returns signed receipts on successful calls.

curl -i https://api.actiongate.xyz/v1/risk-score
-H "content-type: application/json"
-d '{"actor":{"actor_id":"agent_01"},"action":{"action_type":"transfer","network":"base","asset_symbol":"USDC","amount":"10"}}'

HTTP/2 402 PAYMENT-REQUIRED:

curl -i https://api.actiongate.xyz/v1/risk-score
-H "content-type: application/json"
-H "PAYMENT-SIGNATURE: "
-d '{"actor":{"actor_id":"agent_01"},"action":{"action_type":"transfer","network":"base","asset_symbol":"USDC","amount":"10"}}'

HTTP/2 200 PAYMENT-RESPONSE: {"request_id":"rq_demo_risk","score":18,"severity":"low","confidence":0.81}

Troubleshooting

I connected the MCP server but calls fail with a payment error. That usually means the free tier is exhausted or your x402 wallet is not configured. Use the free tier first, or add PAYTO_ADDRESS plus your wallet credentials for the stdio package.

I received an HTTP 402 response. That is expected once free calls are used up. Retry with an x402-compatible client so it can attach a PAYMENT-SIGNATURE header automatically.

The remote MCP endpoint works in one client but not another. Make sure the client is using Streamable HTTP against https://api.actiongate.xyz/mcp and accepts both JSON and event-stream responses during MCP negotiation.

I need help debugging an integration. Start with https://api.actiongate.xyz/support, then include the request ID from the ActionGate response when you contact support.