Authentication - XentFi API Documentation

Agent tools use two distinct credential types, scoped differently on purpose. Using the wrong one against the wrong surface returns 401.

	Agent API key	WAAS org key
Used by	MCP Tools (`@xentfi/mcp-sdk`)	x402 Facilitator (`@xentfi/x402-facilitator-sdk`)
Scoped to	One Agent + its Policy	Your organization’s WAAS wallet
Headers	`agentApiKey`	`apikey`, `orgid` (both required)
Where to get it	Generated automatically when you create an agent	Dashboard → Settings → API Keys
Who needs it	Anyone running an MCP client on the agent’s behalf	Only the resource server side of an x402 flow — a pure payer needs no XentFi credential at all

Agent API key (MCP Tools)

Create an Agent

dashboard.xentfi.com → Agents → New Agent.

Attach a Policy

Per-transaction/daily/weekly/monthly USD limits, an allowed-recipients list, and optionally allowed hours — enforced server-side on every xentfi_create_payment call.

Get the Agent API Key

After creating the agent, your Agent API Key is generated and displayed once. Copy and store it securely — you won’t be able to see it again.

{
    "mcpServers": {
        "xentfi": {
            "command": "npx",
            "args": [
                "-y",
                "@xentfi/mcp-sdk"
            ],
            "env": {
                "XENTFI_AGENT_API_KEY": "sk_agent_xxx"
            }
        }
    }
}

An agent API key authorizes payments on behalf of that agent. Store it like any other production secret.

WAAS org key (x402 Facilitator)

Same organization-level apiKey/orgId used across the rest of the XentFi platform — see core Authentication for how to generate one from Settings → API Keys.

import { X402FacilitatorClient } from "@xentfi/x402-facilitator-sdk";

const facilitator = new X402FacilitatorClient({
  apiKey: process.env.WAAS_API_KEY!,
  orgId: process.env.WAAS_ORG_ID!,
});

The facilitator URL and relayer wallet are fixed on the backend — apiKey/orgId are the only two options the client takes. Header names are lowercase (apikey/orgid).

Only the resource-server side (verify/settle) needs this credential. A pure payer signs offline with signEip3009Authorization and needs no XentFi credential at all — see essentials/x402.

Troubleshooting

401 on an MCP tool call

XENTFI_AGENT_API_KEY didn’t reach the process, or the agent’s status is SUSPENDED/REVOKED (xentfi_get_agent_info shows this). See Error Handling.

401/403 from verify() or settle()

Invalid or missing WAAS apiKey/orgId — double-check against the dashboard, and confirm you’re using the lowercase apikey/orgid header names if calling the facilitator’s REST endpoints directly rather than through the SDK.

Next steps

Tools Reference

Every MCP tool.

x402 Reference

X402FacilitatorClient methods and types.

​Agent API key (MCP Tools)

​WAAS org key (x402 Facilitator)

​Troubleshooting

​Next steps

Tools Reference

x402 Reference

Agent API key (MCP Tools)

WAAS org key (x402 Facilitator)

Troubleshooting

Next steps