@secondlayer/sdk 6.19.0 → 6.21.0

package/README.md

@@ -328,8 +328,15 @@ const { data } = await sl.subgraphs.list();
 // Get
 const subgraph = await sl.subgraphs.get("my-subgraph");
 
-// Query table
-const rows = await sl.subgraphs.queryTable("my-subgraph", "transfers", {
+// Open read (/v1) — keyless for public subgraphs; pass apiKey for your private ones
+const { rows, next_cursor, tip } = await sl.subgraphs.rows("my-subgraph", "transfers", {
+  order: "desc",
+  limit: 50,
+  // cursor: next_cursor — pass back to resume
+});
+
+// Authed control-plane query (/api)
+const page = await sl.subgraphs.queryTable("my-subgraph", "transfers", {
   sort: "block_height",
   order: "desc",
   limit: 50,
@@ -344,8 +351,12 @@ const spec = await sl.subgraphs.openapi("my-subgraph");
 const source = await sl.subgraphs.getSource("my-subgraph");
 const gaps = await sl.subgraphs.gaps("my-subgraph");
 
-// Deploy
-const result = await sl.subgraphs.deploy({ name, sources, schema, handlerCode });
+// Deploy — managed deploys default visibility "public", BYO default "private"
+const result = await sl.subgraphs.deploy({ name, sources, schema, handlerCode, visibility: "public" });
+
+// Flip visibility — publish claims the global public name (409 PUBLIC_NAME_TAKEN if claimed)
+await sl.subgraphs.publish("my-subgraph");
+await sl.subgraphs.unpublish("my-subgraph");
 ```
 
 Stream rows live with the typed client — each table exposes `subscribe`
@@ -483,6 +494,52 @@ verifySecondlayerSignature(
 Prefer the per-subscription HMAC (Standard Webhooks) secret instead? Use
 `verifyWebhookSignature(rawBody, headers, secret)` — raw body first.
 
+## x402 pay-per-call (accountless)
+
+Call the public `/v1/*` reads with **no API key, no account, no Stripe** — pay a
+few hundredths of a cent per request from a Stacks wallet. Payment is **gasless**
+(you sign; we sponsor the STX fee) and uses standard **x402 v2** on `stacks:1`.
+Supported assets: **sBTC** (default), **USDCx**, **STX**.
+
+> Keyed (`sk-sl_`) requests bypass x402 and bill through your plan — x402 is for
+> accountless callers.
+
+Drop-in `fetch` that pays on `402` automatically:
+
+```typescript
+import { withX402, readX402Receipt } from "@secondlayer/sdk";
+import { privateKeyToAccount } from "@secondlayer/stacks/accounts";
+
+const x402fetch = withX402(fetch, {
+  account: privateKeyToAccount(process.env.AGENT_STACKS_KEY!), // funded with sBTC/USDCx
+  preferAssets: ["sBTC", "USDCx", "STX"],   // optional (this is the default)
+  maxAmountPerCall: { sBTC: 2000n },        // optional spend guard (atomic units)
+});
+
+const res = await x402fetch(
+  "https://api.secondlayer.tools/v1/index/events?event_type=ft_transfer",
+);
+const data = await res.json();
+readX402Receipt(res); // { success, txid, payer, network } | null
+```
+
+Or a small client returning `{ data, payment }`:
+
+```typescript
+import { createX402Client } from "@secondlayer/sdk";
+
+const sl = createX402Client({ account, baseUrl: "https://api.secondlayer.tools" });
+const { data, payment } = await sl.get("/v1/index/events", {
+  query: { event_type: "ft_transfer" },
+});
+```
+
+The SDK selects an offer by `preferAssets` (skipping any over `maxAmountPerCall`,
+else throws `X402SpendGuardError`), auto-resolves your account nonce, signs
+origin-only, and retries. A paid call settles on-chain before returning
+(confirmed-tier today, ~seconds; near-instant optimistic serve for Index/Streams
+is rolling out). Discover capabilities at `GET /x402/supported`.
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.ts

@@ -52,6 +52,16 @@ interface SubgraphOperationStatus {
 	createdAt: string;
 	updatedAt: string;
 }
+/** /v1 cursor envelope for subgraph table reads. */
+interface SubgraphRowsEnvelope<T = unknown> {
+	rows: T[];
+	next_cursor: string | null;
+	tip: {
+		block_height: number
+		subgraph_height: number
+		blocks_behind: number
+	};
+}
 interface BundleSubgraphResponse {
 	ok: true;
 	name: string;
@@ -94,6 +104,29 @@ declare class Subgraphs extends BaseClient {
 	}): Promise<{
 		message: string
 	}>;
+	/**
+	* Publish: claim the name in the global public namespace and open anon
+	* reads on /v1/subgraphs/:name. 409 PUBLIC_NAME_TAKEN if another account
+	* holds the public name.
+	*/
+	publish(name: string): Promise<{
+		name: string
+		visibility: "public"
+		url: string
+	}>;
+	/** Make reads private again (owning account's bearer key required). */
+	unpublish(name: string): Promise<{
+		name: string
+		visibility: "private"
+	}>;
+	/**
+	* Open /v1 read: cursor-paginated rows. Anon works for public subgraphs;
+	* pass an apiKey on the client for private ones. Resume with the returned
+	* `next_cursor`.
+	*/
+	rows<T = unknown>(name: string, table: string, params?: Omit<SubgraphQueryParams, "offset" | "sort"> & {
+		cursor?: string
+	}): Promise<SubgraphRowsEnvelope<T>>;
 	/** Recent reindex/backfill operations for a subgraph, newest first. */
 	operations(name: string): Promise<{
 		operations: SubgraphOperationStatus[]
@@ -240,155 +273,6 @@ declare class Contracts extends BaseClient {
 		includeAbi?: boolean
 	}): Promise<ContractSummary | null>;
 }
-/**
-* Typed client for the Foundation Datasets REST API (`/v1/datasets/*`).
-*
-* Most datasets are cursor-paginated event lists with a uniform `list`/`walk`
-* surface; a few (bns names/namespaces/resolve, network-health) are
-* offset/single-object/summary and get bespoke methods. Query params are typed
-* per dataset; rows are `DatasetRow` (JSON) in v1 — per-dataset row interfaces
-* are a fast-follow.
-*/
-/** A dataset row — flat JSON object. Per-dataset interfaces are a follow-up. */
-type DatasetRow = Record<string, unknown>;
-/** Filters shared by every cursor-paginated dataset. */
-interface CursorListParams {
-	cursor?: string;
-	limit?: number;
-	fromBlock?: number;
-	toBlock?: number;
-}
-interface CursorEnvelope {
-	rows: DatasetRow[];
-	next_cursor: string | null;
-	tip?: {
-		block_height: number
-	};
-}
-type RangeFilters = CursorListParams;
-type StxTransfersParams = RangeFilters & {
-	sender?: string
-	recipient?: string
-};
-type SbtcEventsParams = RangeFilters & {
-	topic?: string
-	address?: string
-};
-type SbtcTokenEventsParams = RangeFilters & {
-	eventType?: string
-	sender?: string
-	recipient?: string
-};
-type Pox4CallsParams = RangeFilters & {
-	functionName?: string
-	stacker?: string
-	delegateTo?: string
-	signerKey?: string
-	rewardCycle?: number
-	/** Any-role: matches caller OR stacker OR delegate_to. */
-	address?: string
-};
-type BurnchainRewardsParams = RangeFilters & {
-	/** Filter to one Bitcoin reward address. */
-	recipient?: string
-};
-type BurnchainRewardSlotsParams = RangeFilters & {
-	/** Filter to one reward-set Bitcoin address. */
-	holder?: string
-};
-type BnsEventsParams = RangeFilters & {
-	topic?: string
-	namespace?: string
-	name?: string
-	owner?: string
-};
-type BnsNamespaceEventsParams = RangeFilters & {
-	status?: string
-	namespace?: string
-};
-type BnsMarketplaceEventsParams = RangeFilters & {
-	action?: string
-	bnsId?: string
-};
-type CursorDataset<P> = {
-	list: (params?: P) => Promise<CursorEnvelope>
-	walk: (params?: P & {
-		batchSize?: number
-		signal?: AbortSignal
-	}) => AsyncIterable<DatasetRow>
-};
-/** Cursor-paginated dataset slugs → REST path + envelope row key. */
-declare const CURSOR_SLUGS: Record<string, {
-	path: string
-	rowKey: string
-}>;
-declare class Datasets extends BaseClient {
-	private catalogPromise?;
-	constructor(options?: Partial<SecondLayerOptions>);
-	/** Dataset catalog + freshness (the discovery endpoint). */
-	listDatasets(): Promise<unknown>;
-	/**
-	* Generic read by slug for ANY catalog dataset — cursor or bespoke. Resolves
-	* the slug against the live `/v1/datasets` catalog (so datasets added
-	* server-side work with no SDK change), issues the GET, and normalizes the
-	* response into a uniform `{ rows, next_cursor, tip }` envelope. Single-object
-	* datasets (bns/resolve, network-health/summary) come back as 0-or-1 rows.
-	* Accepts both family (`sbtc-events`) and path (`sbtc/events`) slug forms.
-	* Prefer this over {@link query} unless you specifically need cursor-only
-	* semantics.
-	*/
-	get(slug: string, params?: Record<string, unknown>): Promise<CursorEnvelope>;
-	/**
-	* Generic cursor query by slug — used by the CLI. Params are passed through as
-	* REST query keys (snake_case), so callers can use the documented filter names
-	* directly. Throws for non-cursor (bespoke) datasets — use {@link get} for
-	* those (and for slugs added to the catalog after this SDK was built).
-	*/
-	query(slug: string, params?: Record<string, unknown>): Promise<CursorEnvelope>;
-	readonly stxTransfers: CursorDataset<StxTransfersParams>;
-	readonly sbtcEvents: CursorDataset<SbtcEventsParams>;
-	readonly sbtcTokenEvents: CursorDataset<SbtcTokenEventsParams>;
-	readonly pox4Calls: CursorDataset<Pox4CallsParams>;
-	readonly burnchainRewards: CursorDataset<BurnchainRewardsParams>;
-	readonly burnchainRewardSlots: CursorDataset<BurnchainRewardSlotsParams>;
-	readonly bnsEvents: CursorDataset<BnsEventsParams>;
-	readonly bnsNamespaceEvents: CursorDataset<BnsNamespaceEventsParams>;
-	readonly bnsMarketplaceEvents: CursorDataset<BnsMarketplaceEventsParams>;
-	/** BNS names — offset-paginated. */
-	bnsNames(params?: {
-		namespace?: string
-		owner?: string
-		limit?: number
-		offset?: number
-	}): Promise<{
-		names: DatasetRow[]
-	}>;
-	/** All BNS namespaces (no pagination). */
-	bnsNamespaces(): Promise<{
-		namespaces: DatasetRow[]
-	}>;
-	/** Resolve a fully-qualified BNS name → single record. */
-	bnsResolve(fqn: string): Promise<{
-		name: DatasetRow | null
-	}>;
-	/** Network health summary. */
-	networkHealth(): Promise<{
-		summary: DatasetRow
-	}>;
-	private requestPath;
-	/** Resolve a slug → relative path + row key. Known cursor slugs take a
-	*  network-free fast path; anything else is matched against the live catalog
-	*  by family name or path tail. */
-	private resolveDataset;
-	/** Fetch + cache the catalog families. Caches the in-flight promise so
-	*  concurrent first-calls share one request; no TTL — agent sessions are
-	*  short-lived, and a new client picks up newly added datasets. */
-	private loadCatalog;
-	/** Map camelCase filter fields to snake_case query keys (dropping pagination
-	*  controls) and build the canonical query suffix. */
-	private paramsToQuery;
-	private cursorDataset;
-}
 import { RewardSet } from "@secondlayer/shared/node/consensus";
 import { MerkleProofStep } from "@secondlayer/shared/node/nakamoto";
 /**
@@ -968,6 +852,30 @@ type MempoolWalkParams = Omit<MempoolListParams, "limit"> & {
 	batchSize?: number
 	signal?: AbortSignal
 };
+/**
+* `index.ftTransfers` — callable shorthand for `.list()`, with `.list`/`.walk`
+* still available: `await sl.index.ftTransfers({ contractId })`.
+*
+* The API accepts `contract_id`/`sender`/`recipient` equality filters only —
+* no amount filtering and no asset-slug resolution on /v1/index/ft-transfers.
+*/
+interface FtTransfersResource {
+	(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
+	list(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
+	walk(params?: FtTransfersWalkParams): AsyncIterable<FtTransfer>;
+}
+/** `index.nftTransfers` — callable shorthand for `.list()` (see {@link FtTransfersResource}). */
+interface NftTransfersResource {
+	(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
+	list(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
+	walk(params?: NftTransfersWalkParams): AsyncIterable<NftTransfer>;
+}
+/** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
+interface IndexEventsResource {
+	(params: EventsListParams): Promise<EventsEnvelope>;
+	list(params: EventsListParams): Promise<EventsEnvelope>;
+	walk(params: EventsWalkParams): AsyncIterable<IndexEvent>;
+}
 /** Per-event-type filter vocabulary in the {@link IndexDiscovery} doc. */
 type IndexEventTypeFilters = {
 	columns?: string[]
@@ -992,19 +900,13 @@ declare class Index extends BaseClient {
 	* learn what's queryable (and which types accept `trait`) instead of hardcoding.
 	*/
 	discover(): Promise<IndexDiscovery>;
-	readonly ftTransfers: {
-		list: (params?: FtTransfersListParams) => Promise<FtTransfersEnvelope>
-		walk: (params?: FtTransfersWalkParams) => AsyncIterable<FtTransfer>
-	};
-	readonly nftTransfers: {
-		list: (params?: NftTransfersListParams) => Promise<NftTransfersEnvelope>
-		walk: (params?: NftTransfersWalkParams) => AsyncIterable<NftTransfer>
-	};
-	/** Generic decoded events by `event_type` (the full /v1/index/events surface). */
-	readonly events: {
-		list: (params: EventsListParams) => Promise<EventsEnvelope>
-		walk: (params: EventsWalkParams) => AsyncIterable<IndexEvent>
-	};
+	/** Callable: `index.ftTransfers(params)` ≡ `index.ftTransfers.list(params)`. */
+	readonly ftTransfers: FtTransfersResource;
+	/** Callable: `index.nftTransfers(params)` ≡ `index.nftTransfers.list(params)`. */
+	readonly nftTransfers: NftTransfersResource;
+	/** Generic decoded events by `event_type` (the full /v1/index/events surface).
+	*  Callable: `index.events(params)` ≡ `index.events.list(params)`. */
+	readonly events: IndexEventsResource;
 	readonly contractCalls: {
 		list: (params?: ContractCallsListParams) => Promise<ContractCallsEnvelope>
 		walk: (params?: ContractCallsWalkParams) => AsyncIterable<IndexContractCall>
@@ -1389,6 +1291,36 @@ type StreamsEventsConsumeParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
+/**
+* One yielded page from {@link StreamsClient.consume} — the
+* `GET /v1/streams/events` envelope verbatim, with `next_cursor` renamed to
+* `cursor` (the checkpoint to persist and resume from).
+*/
+type StreamsBatch = {
+	/** Canonical events of this page, in cursor order. */
+	events: StreamsEvent[]
+	/** Checkpoint after this page — pass back as `consume({ cursor })` to resume. */
+	cursor: string | null
+	tip: StreamsTip
+	/** Chain reorgs reported alongside this page; empty when none. */
+	reorgs: StreamsReorg[]
+};
+type StreamsConsumeParams = {
+	/** Resume strictly after this cursor; omit to start from the oldest seekable page. */
+	cursor?: string | null
+	types?: readonly StreamsEventType[]
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
+	/** Events per page (the `limit` query param). Default 100. */
+	batchSize?: number
+	/** Poll interval while caught up at the tip, in ms. Default 2000. */
+	intervalMs?: number
+	/** Abort to end the iteration. */
+	signal?: AbortSignal
+};
 type StreamsEventsConsumeResult = {
 	cursor: string | null
 	pages: number
@@ -1457,6 +1389,21 @@ type StreamsDumps = {
 	download(file: StreamsDumpFile): Promise<Uint8Array>
 };
 type StreamsClient = {
+	/**
+	* Follow Streams as an async iterator of page batches.
+	*
+	* Yields one {@link StreamsBatch} per `GET /v1/streams/events` page — the
+	* existing envelope (`events`, `next_cursor` → `cursor`, `tip`, `reorgs`)
+	* with zero extra API calls. Batches are chosen over per-block groupings
+	* because the envelope is page-keyed, so every yield is exactly one fetch.
+	* Empty pages are skipped; at the tip the iterator re-polls every
+	* `intervalMs` (default 2000) until aborted via `signal`.
+	*
+	* Reorgs are surfaced on the batch (`batch.reorgs`) but the cursor is not
+	* rewound automatically — use `events.consume` with `onReorg` for managed
+	* rollback semantics.
+	*/
+	consume(params?: StreamsConsumeParams): AsyncIterableIterator<StreamsBatch>
 	events: {
 		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>
 		byTxId(txId: string): Promise<StreamsEventsListEnvelope>
@@ -1601,7 +1548,6 @@ interface ContextSnapshot {
 declare class SecondLayer extends BaseClient {
 	readonly streams: StreamsClient;
 	readonly index: Index;
-	readonly datasets: Datasets;
 	readonly contracts: Contracts;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
@@ -1613,6 +1559,21 @@ declare class SecondLayer extends BaseClient {
 	* from `secondlayer://context`, but available to any SDK/CLI consumer. Reads
 	* run concurrently and degrade to `null` per field on failure.
 	*/
+	/**
+	* Up to 10 public reads in one round trip (`POST /v1/batch`). Each item
+	* keeps its own auth/quota/x402 semantics; forwarded credentials (API key,
+	* PAYMENT-BALANCE/SESSION) apply to every item.
+	*/
+	batch(requests: Array<{
+		path: string
+		params?: Record<string, string | number | boolean>
+	}>): Promise<{
+		results: Array<{
+			path: string | null
+			status: number
+			body: unknown
+		}>
+	}>;
 	context(): Promise<ContextSnapshot>;
 }
 /**
@@ -1953,6 +1914,162 @@ declare const Cursor: {
 	}
 };
 type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer | DecodedStxTransfer | DecodedStxMint | DecodedStxBurn | DecodedStxLock | DecodedFtMint | DecodedFtBurn | DecodedNftMint | DecodedNftBurn | DecodedPrint;
+import { X402TokenSymbol } from "@secondlayer/shared/x402";
+import { LocalAccount } from "@secondlayer/stacks/accounts";
+import { StacksChain } from "@secondlayer/stacks/chains";
+/**
+* Client for the x402 pay-per-request rail. Turns a 402 challenge into a signed
+* `PAYMENT-SIGNATURE` and retries — gasless (the agent signs origin-only; the
+* facilitator sponsors the STX fee) and accountless (no key/Stripe/session).
+*
+* Three layers:
+*  - `withX402(fetch, opts)` — drop-in fetch that auto-pays on 402.
+*  - `createX402Client(opts)` — `.get/.post` returning `{ data, payment }`.
+*  - `buildSignedX402Payment` / `readX402Challenge` — primitives for custom transports.
+*/
+type X402Accept = {
+	scheme: "exact"
+	network: string
+	asset: string
+	/** Atomic units. */
+	amount: string
+	payTo: string
+	maxTimeoutSeconds: number
+	extra: {
+		nonce: string
+	}
+};
+type X402Challenge = {
+	x402Version: number
+	accepts: X402Accept[]
+	error?: string
+};
+/** Decoded `PAYMENT-RESPONSE` settlement receipt. */
+type X402Receipt = {
+	success: boolean
+	/** Settlement tier: `optimistic` (served on broadcast-accept, reconciled
+	*  async) or `confirmed` (canonical). Absent on older deployments. */
+	state?: "optimistic" | "confirmed"
+	txid: string
+	payer: string
+	network: string
+};
+/** Bitcoin-native first — sBTC is the compelling micropay asset; USDCx the
+*  dollar peg; STX the fallback. Override via `preferAssets`. */
+declare const DEFAULT_PREFER_ASSETS: X402TokenSymbol[];
+/** Thrown when no offered asset is within the caller's spend guard / preferences. */
+declare class X402SpendGuardError extends Error {
+	constructor(message: string);
+}
+/** Read the x402 challenge from a 402 response — prefer the wire header, fall
+*  back to the JSON body. */
+declare function readX402Challenge(res: Response): Promise<X402Challenge | null>;
+/** Read the settlement receipt from a paid 200 response. */
+declare function readX402Receipt(res: Response): X402Receipt | null;
+type SelectOfferOptions = {
+	preferAssets?: X402TokenSymbol[]
+	maxAmountPerCall?: Partial<Record<X402TokenSymbol, bigint>>
+};
+/** Choose an `accepts[]` entry by preference order, skipping any that exceed the
+*  per-asset spend cap. Throws {@link X402SpendGuardError} if none qualify. */
+declare function selectOffer(challenge: X402Challenge, opts?: SelectOfferOptions): {
+	accept: X402Accept
+	symbol: X402TokenSymbol
+};
+/** Fetch the payer account's next nonce from a Stacks node (`/v2/accounts`). */
+declare function resolveAccountNonce(address: string, nodeUrl?: string): Promise<number>;
+type BuildSignedX402PaymentOptions = {
+	challenge: X402Challenge
+	account: LocalAccount
+	/** The payer account's next nonce. */
+	accountNonce: bigint | number | string
+	/** Preferred asset string (e.g. an sBTC/USDCx id). Defaults to the first offer. */
+	asset?: string
+	chain?: StacksChain
+};
+/** Build a signed, base64 `PAYMENT-SIGNATURE` header for one `accepts[]` entry. */
+declare function buildSignedX402Payment(opts: BuildSignedX402PaymentOptions): Promise<{
+	header: string
+	accept: X402Accept
+}>;
+type WithX402Options = SelectOfferOptions & {
+	account: LocalAccount
+	/** Prepaid-credit token (PAYMENT-BALANCE) from a prior deposit — calls
+	*  debit the tab server-side instead of settling on-chain per call. */
+	balanceToken?: string
+	/** Autonomous treasury policy: when the tab's remaining balance (read from
+	*  X-BALANCE-REMAINING-USD) drops below `whenBelow`, deposit `usd` more in
+	*  the background (one on-chain payment) and adopt the fresh token. */
+	topUp?: {
+		usd: number
+		whenBelow: number
+	}
+	/** Override the payer nonce; auto-resolved from `nodeUrl` when omitted. */
+	accountNonce?: bigint | number | string
+	/** Node for auto-nonce lookup. Defaults to {@link DEFAULT_NONCE_NODE_URL}. */
+	nodeUrl?: string
+	chain?: StacksChain
+	/** Fired just before the paid retry (the call then blocks on confirmed-tier
+	*  settle, or returns near-instantly on an optimistic surface). */
+	onSettling?: (info: {
+		asset: string
+		amount: string
+	}) => void
+	/** Abort the paid retry after this long. */
+	timeoutMs?: number
+};
+type X402Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/**
+* Wrap a `fetch` so requests transparently pay on 402: select an offer (by
+* `preferAssets` + `maxAmountPerCall`), resolve the nonce, sign origin-only, and
+* retry once with `PAYMENT-SIGNATURE`. Returns the final `Response` (read the
+* receipt with {@link readX402Receipt}).
+*
+* @example
+* const x402fetch = withX402(fetch, { account });
+* const res = await x402fetch("https://api.secondlayer.tools/v1/index/events?event_type=ft_transfer");
+*/
+declare function withX402(baseFetch: typeof fetch, opts: WithX402Options): X402Fetch;
+type X402ClientOptions = WithX402Options & {
+	baseUrl: string
+	/** Override the underlying fetch (tests). */
+	fetch?: typeof fetch
+};
+type X402Result<T = unknown> = {
+	data: T
+	/** Settlement receipt, or null if the response carried none. */
+	payment: X402Receipt | null
+	response: Response
+};
+type X402Client = {
+	get<T = unknown>(path: string, o?: {
+		query?: Record<string, string>
+	}): Promise<X402Result<T>>
+	post<T = unknown>(path: string, o?: {
+		body?: unknown
+	}): Promise<X402Result<T>>
+};
+/**
+* A small client over {@link withX402}: `.get/.post` against `baseUrl`, returning
+* parsed JSON plus the settlement receipt.
+*
+* @example
+* const sl = createX402Client({ account, baseUrl: "https://api.secondlayer.tools" });
+* const { data, payment } = await sl.get("/v1/index/events", { query: { event_type: "ft_transfer" } });
+*/
+declare function createX402Client(opts: X402ClientOptions): X402Client;
+/** Caller-supplied fetch that re-runs the request with the given extra headers. */
+type X402FetchFn = (extraHeaders: Record<string, string>) => Promise<Response>;
+type PayAndRetryOptions = Omit<WithX402Options, never> & {
+	/** Required here (use `withX402` for auto-nonce). */
+	accountNonce: bigint | number | string
+};
+/**
+* Low-level: run a request via a caller-controlled fetch; if it 402s, pay and
+* retry once. Prefer {@link withX402} for the common case (it auto-resolves the
+* nonce + selects the asset). Kept for custom transports.
+*/
+declare function payAndRetry(doFetch: X402FetchFn, opts: PayAndRetryOptions): Promise<Response>;
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
 import { ByoBreakingChangeDetails } from "@secondlayer/shared/errors";
 /**
@@ -2125,4 +2242,4 @@ declare function toJsonSafe(value: unknown): unknown;
 /** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
 *  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
 declare function decodeClarityValue(hex: string): unknown;
-export { verifyWebhookSignature, verifyTransactionProof, verifySecondlayerSignature, trigger, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StackingWalkParams, StackingListParams, StackingEnvelope, SecondLayerOptions, SecondLayer, ScopedKeyProduct, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStackingAction, IndexReorg, IndexPostCondition, IndexMempoolTransaction, IndexEventTypeFilters, IndexEventType, IndexEvent, IndexDiscovery, IndexContractCall, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ChainTriggerType, ChainTrigger, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CURSOR_SLUGS, ByoBreakingChangeError, ByoBreakingChangeDetails, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };
+export { withX402, verifyWebhookSignature, verifyTransactionProof, verifySecondlayerSignature, trigger, toJsonSafe, selectOffer, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createX402Client, createStreamsClient, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StackingWalkParams, StackingListParams, StackingEnvelope, SelectOfferOptions, SecondLayerOptions, SecondLayer, ScopedKeyProduct, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStackingAction, IndexReorg, IndexPostCondition, IndexMempoolTransaction, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEvent, IndexDiscovery, IndexContractCall, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ChainTriggerType, ChainTrigger, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };