@xyz17711/url-extract

Typed TypeScript client for url-extract-service, part of the 17711.xyz microservice fleet -- pay-per-call APIs settled in USDC via x402, listed on x402scan.

Install

npm install @xyz17711/url-extract

Methods

| Method | Description | | --- | --- | | getCompanyProfile | [Deprecated - use company_profile_get_profile] Company profile from a domain or a name as valid JSON ($0.009, x402) | | getStructuredData | URL extract with a question: ask any web page a question and get structured data as JSON that matches your schema ($0.02, x402) |

Quickstart

import { Client } from "@xyz17711/url-extract";

const client = new Client(); // talks to https://api.17711.xyz/registry/url-extract-service by default
// see the Methods table above for every available call and its request/response type

Pass another base URL (self-hosted instance, test server) as the first argument: new Client("https://my-host.example/registry/url-extract-service").

Paying past the free quota

Every gated tool allows a small number of free calls per day; beyond that it returns a 402 challenge. Without a wallet configured, this client throws PaymentRequiredError with the price, network, and payee address attached:

import { Client, PaymentRequiredError } from "@xyz17711/url-extract";

const client = new Client();
try {
  await client.getCompanyProfile(/* ... */);
} catch (e) {
  if (e instanceof PaymentRequiredError) {
    console.log(`needs ${e.priceUsdc} USDC on ${e.network}, payable to ${e.payTo}`);
  }
}

To pay automatically, configure a wallet on the client -- the private key should come from your own environment/secrets manager, never a literal string in source code:

import { Client } from "@xyz17711/url-extract";

const client = new Client({
  x402PrivateKey: process.env.X402_PRIVATE_KEY,
  x402ExpectedNetwork: "eip155:8453", // Base mainnet; use eip155:84532 for Base Sepolia testnet
  x402MaxPaymentUsdc: 0.01,           // refuse any single call above this
  x402MaxTotalSpendUsdc: 1.0,         // refuse once this WALLET's lifetime spend would exceed it
});

Never commit a private key. Both spend caps are required together with the key -- a wallet with real funds and no explicit caps refuses to construct at all (WalletConfigError), on purpose. The cumulative cap is tracked per wallet address, shared by every Client you construct with that same key in this process.

LangChain.js

import { Client } from "@xyz17711/url-extract";
import { UrlExtractToolkit } from "@xyz17711/url-extract/langchain";

const client = new Client({ /* ...wallet options... */ });
const tools = new UrlExtractToolkit(client).getTools();

Requires the optional @langchain/core+zod peer dependencies (npm install @langchain/core zod) -- importing the base package above never requires them; only @xyz17711/url-extract/langchain does.

License

MIT -- see LICENSE, shared by every language's client library in the clients repo this package lives in.