RouterClient: TypeScript API Reference

RouterClient is the SELAT Router SDK entry point for TypeScript applications that need fetch-like access to paid endpoints.

RouterClient sends a request through SELAT Router, returns an unpaid upstream response unchanged when no payment is required, and completes one signed payment replay only when the router returns a valid 402 Payment Required challenge. It supports a private key or any SDK-compatible PaymentSigner. 1

import { RouterClient, createViemSigner } from "@selat-ai/router-client";

const signer = createViemSigner(
  process.env.X402_CLIENT_PRIVATE_KEY as `0x${string}`
);

const client = new RouterClient({
  chain: "base",
  signer
});

Constructor

new RouterClient({
  chain,
  privateKey,
  signer,
  routerUrl,
  requestTimeoutMs,
  defaultHeaders
})

The chain option is required. You must supply a signer or a privateKey; when a signer is supplied, it is used as the signing implementation. 1

Option	Type	Required	Default	Description
`chain`	`SupportedChainName`	Yes	None	Chain key used to select a compatible payment option from the challenge.
`signer`	`PaymentSigner`	One of `signer` or `privateKey`	None	A constructed signer object for the selected wallet or signing service.
`privateKey`	`0x${string}`	One of `signer` or `privateKey`	None	Creates an in-process Viem signer. Use only where local key handling is acceptable.
`routerUrl`	`string`	No	`https://router.selat.ai`	SELAT Router base URL.
`requestTimeoutMs`	`number`	No	`30000`	Timeout applied to each router request leg.
`defaultHeaders`	`Record<string, string>`	No	`{}`	Headers merged into every request before request-specific headers.

Send a paid request with `fetch`

client.fetch(input, init?) accepts a full target URL and a fetch-compatible request initializer. It returns a standard Promise<Response>, so applications can use familiar status, header, and body handling. 1

const response = await client.fetch(
  "https://upstream.example.com/v1/data",
  {
    method: "GET"
  }
);

if (!response.ok) {
  throw new Error(`Upstream request failed: ${response.status}`);
}

console.log(await response.text());

Request lifecycle

The payment flow consists of a maximum of two router requests for one fetch call. The SDK does not sign or replay ordinary non-402 responses. 1

Step	SDK behavior	Outcome
1. Route the request	Builds a SELAT Router proxy URL and sends the original method, body, headers, and abort signal.	The upstream result is returned when it is not `402`.
2. Parse a payment challenge	For a `402`, validates the `x-selat-quote-id` and `payment-required` headers.	A malformed or incompatible challenge raises `QuoteParseError`.
3. Build a payment	Selects a compatible `GatewayWalletBatched` accept option for the chosen chain and asks the signer for the EIP-712 signature.	Produces a payment payload.
4. Replay once	Re-sends the routed request with `PAYMENT-SIGNATURE` and the quote ID.	Returns the final upstream `Response`.

Each of the two router request legs receives its own requestTimeoutMs window. Set a value that accommodates your expected upstream latency, but use an AbortSignal as well when the caller needs independent cancellation. 1

Configure request options

RouterFetchOptions extends the standard RequestInit options and adds preferProtocol. Use normal fetch options for HTTP method, headers, request body, and cancellation. 1

Option	Type	Default	Description
`method`	`string`	`GET`	HTTP method forwarded to the target endpoint.
`headers`	`HeadersInit`	None	Request-specific headers. These are merged with `defaultHeaders`; request headers can override defaults.
`body`	`BodyInit \| null`	None	Request body for POST, PUT, PATCH, and other body-bearing methods.
`signal`	`AbortSignal`	None	Cancels the active request leg.
`preferProtocol`	`"x402" \| "mpp"`	`"mpp"`	Adds a protocol preference hint as `x-selat-prefer-protocol`.

POST example

const response = await client.fetch("https://upstream.example.com/v1/jobs", {
  method: "POST",
  headers: {
    "content-type": "application/json"
  },
  body: JSON.stringify({
    query: "pricing"
  }),
  preferProtocol: "x402"
});

Protocol preference is a hint. Choose x402 or mpp only when your integration needs to express a rail preference; the default is mpp. 1

Bind a base URL with `createFetch`

Use createFetch({ baseUrl }) to create a fetch-like function for a known upstream. It resolves each relative path against the base URL, then routes the resulting absolute URL through the same payment flow. 1

const apiFetch = client.createFetch({
  baseUrl: "https://upstream.example.com"
});

const response = await apiFetch("/v1/data", {
  method: "GET"
});

This pattern keeps endpoint call sites concise while retaining the same signer, timeout, headers, and protocol configuration.

Claim and track refunds

Use the quote ID from a completed paid request to create a refund claim. refundClaim(quoteId) returns the new RefundRequest. Use refundQuery(quoteId) to retrieve its latest status. Both methods authenticate the request with the RouterClient signer. 1

const quoteId = "selatx<quote-id>";

const refund = await client.refundClaim(quoteId);
console.log(refund.id, refund.status);

const status = await client.refundQuery(quoteId);
console.log(status.status, status.refundTxId);

Method	Returns	Description
`refundClaim(quoteId)`	`Promise<RefundRequest>`	Creates a refund claim for the quote ID.
`refundQuery(quoteId)`	`Promise<RefundStatusResult>`	Retrieves the latest refund status for the quote ID.

RefundRequest includes the claim id, quoteId, requesting wallet, current status, and createdAt timestamp. RefundStatusResult includes the quoteId and status; it can also include chainId and refundTxId when available. A refund status is one of new, pending_review, approved, processing, succeeded, or failed. If the Router rejects the request or cannot return a valid result, either method throws an Error whose message includes the HTTP status and the returned detail. Handle this separately from payment-challenge parsing errors.

Handle SDK errors

The SDK exports a base error type and two specialized errors. Catch the most specific type that helps your application provide a useful recovery path. 1

Error	When it occurs	Recommended response
`RouterClientConfigError`	`chain` is missing or neither a signer nor private key is available.	Correct application configuration before retrying.
`QuoteParseError`	A `402` challenge is missing required headers, contains invalid data, or lacks a compatible Gateway-batched payment option.	Inspect the endpoint and selected chain; do not treat the response as payable without a valid quote.
`RouterSdkError`	Base class for SDK-specific errors.	Use when a shared SDK error boundary is sufficient.

import {
  QuoteParseError,
  RouterClientConfigError,
  RouterSdkError
} from "@selat-ai/router-client";

try {
  const response = await client.fetch("https://upstream.example.com/v1/data");
  console.log(await response.text());
} catch (error) {
  if (error instanceof RouterClientConfigError) {
    console.error("Check the SELAT chain and signer configuration.");
  } else if (error instanceof QuoteParseError) {
    console.error("The endpoint returned an invalid or incompatible payment challenge.");
  } else if (error instanceof RouterSdkError) {
    console.error("SELAT Router SDK error:", error.message);
  } else {
    throw error;
  }
}

Select a signer and chain

Use the Signers guide to choose a private key, Circle Agent Wallet, HTTP remote signer, custom remote signer, or Circle Developer-Controlled Wallet. The chain must match a payment option offered by the returned challenge and the wallet’s available Gateway balance. See Chains for the fund chains and the outbound settlement rails; for the exact set a specific runtime accepts, query its payment tooling. 1 For the first complete request, continue to the SDK Quickstart. For source examples, see SDK Examples.

Overview

Agentic payments

Transactability

HTTP 402

SELAT Plugins

SELAT CLI

Catalog MCP

SELAT Router SDK

Skills

Glossary

RouterClient: TypeScript API Reference

RouterClient: TypeScript API Reference

Constructor

Send a paid request with `fetch`

Request lifecycle

Configure request options

POST example

Bind a base URL with `createFetch`

Claim and track refunds

Handle SDK errors

Select a signer and chain

References

​RouterClient: TypeScript API Reference

​Constructor

​Send a paid request with fetch

​Request lifecycle

​Configure request options

​POST example

​Bind a base URL with createFetch

​Claim and track refunds

​Handle SDK errors

​Select a signer and chain

​References

RouterClient: TypeScript API Reference

Constructor

Send a paid request with `fetch`

Request lifecycle

Configure request options

POST example

Bind a base URL with `createFetch`

Claim and track refunds

Handle SDK errors

Select a signer and chain

References