Docs
/
Getting started
/
Use it from an agent (MCP)

Use it from an agent (MCP)

Every endpoint is also available as a tool over MCP, at the same prices. An agent finds an endpoint, then pays for each call with USDC through x402, with no account and no API key.

Endpoint

Point an MCP client at https://api.getwaluku.com/mcp. It speaks Streamable HTTP (JSON-RPC over POST) and keeps no session.

Tools and prices

Three free tools find and describe endpoints. Paid calls go through one of four tools, one per price, so the price is known before you pay.

Tool	Price	Use it for
`list_actors`	Free	The actors you can call, with route counts and price range.
`search_routes`	Free	Find endpoints by keyword. Returns path, summary, price and the tool to call it with.
`describe_route`	Free	Parameters, allowed values, cache TTL and price of one endpoint.
`call_reference`	$0.005	Suggestions, filters, category lists and other reference data. 48 endpoints.
`call_standard`	$0.008	One entity: a detail page, profile, article, weather point. 67 endpoints.
`call_list`	$0.012	Search results, feeds, reviews and other paginated lists. 119 endpoints.
`call_premium`	$0.020	Travel prices and availability, live positions, routes, quotes, odds. 42 endpoints.

How a paid call works

Call search_routes, then describe_route. It names the call_* tool the endpoint needs.
Call that tool with path (the concrete path, like /agoda/hotels/search) and query (name to value).
The first reply is a payment request. An x402-capable client signs it and retries, and the reply carries the data and the settlement receipt.

A wrong path, a path with a query string, or a tool that does not match the endpoint's price is refused before any payment is asked. A call that fails is not charged. Cached responses are still paid, as with the REST API.

Connect a client

A plain MCP client can list the tools and use the free ones, but it cannot pay: use an x402-capable client such as @x402/mcp. The wallet must be an ordinary account; smart-account and EIP-7702 wallets are rejected.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

import { wrapMCPClientWithPayment, x402Client } from "@x402/mcp";

import { ExactEvmScheme } from "@x402/evm/exact/client";

import { privateKeyToAccount } from "viem/accounts";

// An ordinary EVM account (not a smart account) that holds USDC.

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);

const payment = new x402Client().register('eip155:*', new ExactEvmScheme(signer));

payment.registerPolicy((_, reqs) => reqs.filter((r) => BigInt(r.amount) <= 20000n)); // never sign for more than $0.02

const mcp = wrapMCPClientWithPayment(new Client({ name: "my-agent", version: "1.0.0" }), payment, { autoPayment: true });

await mcp.connect(new StreamableHTTPClientTransport(new URL("https://api.getwaluku.com/mcp")));

const found = await mcp.callTool("search_routes", { query: "hotel search" }); // free

const result = await mcp.callTool("call_list", { path: "/agoda/hotels/search", query: { q: "bali" } });

console.log(result.paymentMade, result.content);