@agentcash/search

Typed client for the AgentCash search API with automatic handling of the SIWx auth handshake.

Install

pnpm add @agentcash/search

Usage

import { search } from '@agentcash/search';

import type { SIWxSigner } from '@agentcash/search';

const signer: SIWxSigner = /* create or load your SIWX signer */;

const response = await search(
  {
    query: 'company data enrichment',
    limit: 5,
  },
  signer
);

for (const result of response.results) {
  console.log(result.method, result.origin.url + result.path, result.price);
}

What it does

@agentcash/search exports a search() function that:

1. Builds a POST /api/search request against https://agentcash.dev by default.
2. Sends the request without credentials and expects the API to return 402 Payment Required.
3. Reads the x402 response and extracts the sign-in-with-x extension.
4. Selects the Base SIWX chain (eip155:8453) from the extension metadata.
5. Uses the signer you provide to create and encode a SIWX payload.
6. Retries the same search request with a SIGN-IN-WITH-X header.
7. Returns the JSON response as a typed SearchResponse.

The caller must provide a compatible SIWxSigner from @x402/extensions/sign-in-with-x. The package does not handle x402 payment handshakes.

API

search(body, signer, options?)

function search(body: SearchInput, signer: SIWxSigner): Promise<SearchResponse>;

body is the search request:

• query: natural-language description of the paid API or capability to find. Required, minimum 1 character, maximum 500 characters.
• broad: optional flag to include resources without usage signals. Defaults to false.
• limit: optional maximum result count for the requested page. Must be an integer from 1 through 50. Defaults to 10.
• page: optional one-based result page. Must be an integer greater than or equal to 1. Defaults to 1.

The API trims the query before catalog search. If the trimmed query is empty or contains no alphanumeric characters, the API returns an empty result set.

signer is used only to answer the SIWX challenge returned by AgentCash.

const response = await search(
  { query: 'weather APIs', broad: true, page: 2 },
  signer
);

Response shape

The response contains the echoed query, current page, total result count, and a list of matching paid endpoints.

Each result includes:

• endpoint metadata: method, path, summary, semanticDescription
• optional access metadata: authMode, price
• ranking metadata: score
• provider metadata under origin, including URL, title, favicon, AgentCash origin IDs, and supported payment protocols

score is rounded to three decimal places.

The catalog search considers up to 100 semantic candidates before pagination. It first filters to semantic scores above 0.2; if that returns no rows, it retries with a fallback threshold above 0.05. Removed, deprecated, unindexed, unembedded, and search-excluded resources are not returned.

Errors

The client throws when:

• the initial search request does not return 402 Payment Required
• the x402 response does not include a SIWX extension
• the SIWX extension does not advertise Base SIWX support (eip155:8453)
• the authenticated retry returns a non-2xx response
• the underlying fetch() or signer operation fails

Handle those failures with normal try / catch logic.