@piprail/sdk 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.11.0] — 2026-06-09
+
+### Added — Agent-friendly discovery lifecycle
+- **`register()` outcomes now tell an agent when/where a listing is findable.** Each
+  `RegisterOutcome` carries a `visibility: 'live' | 'pending-review' | 'not-listable'` plus a
+  plain-language `note` — projected from a new exported source-of-truth, **`DIRECTORY_INFO`**
+  (per-index: review mode, auth, chains, `readByDiscover`, caveat). So an agent reads the caveat
+  right where it already is instead of guessing. New exports: `DIRECTORY_INFO`, `getDirectoryInfo`,
+  `decorateOutcome`, and the `DirectoryInfo` / `ListingVisibility` types.
+- **The sharp caveats are now explicit** (in the types, the `note`, and `register()`/`discover()`
+  JSDoc): **402 Index lists a self-registered resource as `pending-review`** (not searchable until
+  approved — verify your domain on 402index.io for instant approval), **`discover()` does NOT read
+  x402scan** (a live x402scan listing won't appear there — don't read its absence as failure), and
+  **CDP Bazaar can't list a backendless PipRail resource at all** (facilitator-coupled).
+
+### Docs — x402 v1/v2 version posture made authoritative
+- A definitive comment in `x402.ts` documents the stance: **emit strict v2, accept liberal v1 + v2**
+  (Postel). v2 *replaced* v1 on the wire; the current reference client `@x402/fetch` is v2, but the
+  original `x402-fetch`/`x402-express`/`x402-next` packages still send v1, so the gate keeps accepting
+  it. PipRail emits no v1 *body* on its own paths; the lone v1 emitter is the `encodeXPaymentHeader`
+  utility (its `x402Version: 1` default is correct — consistent with the v1-flat shape it builds).
+
+### Fixed
+- Corrected stale "searchable within seconds" wording for 402 Index (it added a review queue):
+  `register402Index`'s success `detail` now surfaces the index's own message, and the JSDoc + MCP
+  `piprail_register` tool description reflect the `pending-review` reality.
+
 ## [1.10.0] — 2026-06-09
 
 ### Added — Universal Payments (the standard x402 `exact` rail)
@@ -549,6 +576,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.11.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.10.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.9.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.8.0]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -1305,6 +1305,42 @@ async function resolveNetwork2(opts) {
 }
 
 // src/indexes.ts
+var DIRECTORY_INFO = {
+  "402index": {
+    source: "402index",
+    review: "probe-sync",
+    auth: "none",
+    chains: null,
+    onSuccess: "pending-review",
+    readByDiscover: true,
+    caveat: "402 Index probes your URL on submit, then lists it as PENDING REVIEW \u2014 a self-registered resource is NOT in search until approved. Verify your domain on 402index.io for instant approval; otherwise it appears after manual review, so retry discover() later."
+  },
+  x402scan: {
+    source: "x402scan",
+    review: "probe-sync",
+    auth: "siwx",
+    chains: ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
+    onSuccess: "live",
+    readByDiscover: false,
+    caveat: "x402scan lists Base/Solana only, needs one wallet signature (SIWX), and requires a resolvable input schema (from /openapi.json or the bazaar extension in the 402 body). It goes live on x402scan.com immediately on success \u2014 but discover() does NOT read x402scan, so the listing won't appear in discover() results."
+  },
+  bazaar: {
+    source: "bazaar",
+    review: "settle-coupled",
+    auth: "facilitator-only",
+    chains: null,
+    onSuccess: "not-listable",
+    readByDiscover: true,
+    caveat: "CDP Bazaar has no register endpoint \u2014 it catalogs a resource only when its own facilitator settles a payment. PipRail verifies locally with no facilitator, so a PipRail resource cannot be listed here (you can still READ Bazaar to find others). List on 402 Index or x402scan instead."
+  }
+};
+function getDirectoryInfo(source) {
+  return DIRECTORY_INFO[source];
+}
+function decorateOutcome(o) {
+  const info = DIRECTORY_INFO[o.source];
+  return { ...o, visibility: o.ok ? info.onSuccess : "not-listable", note: info.caveat };
+}
 var BAZAAR_URL = "https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources";
 var INDEX402_SEARCH = "https://402index.io/api/v1/services";
 var INDEX402_REGISTER = "https://402index.io/api/v1/register";
@@ -1457,7 +1493,13 @@ async function register402Index(input) {
       body: JSON.stringify(payload)
     });
     if (res.ok) {
-      return { source: "402index", ok: true, status: res.status, detail: "Listed on 402 Index (searchable at 402index.io)." };
+      const msg = await readIndexMessage(res);
+      return {
+        source: "402index",
+        ok: true,
+        status: res.status,
+        detail: _nullishCoalesce(msg, () => ( "Registered on 402 Index \u2014 pending review (verify your domain on 402index.io for instant approval)."))
+      };
     }
     const why = await readIndexError(res);
     return {
@@ -1470,6 +1512,14 @@ async function register402Index(input) {
     return { source: "402index", ok: false, detail: errMsg(err) };
   }
 }
+async function readIndexMessage(res) {
+  try {
+    const body = await res.json();
+    return typeof body.message === "string" && body.message.length > 0 ? body.message : void 0;
+  } catch (e17) {
+    return void 0;
+  }
+}
 async function readIndexError(res) {
   try {
     const body = await res.json();
@@ -1477,7 +1527,7 @@ async function readIndexError(res) {
       (p) => typeof p === "string" && p.length > 0
     );
     return parts.length ? [...new Set(parts)].join(" \u2014 ") : void 0;
-  } catch (e17) {
+  } catch (e18) {
     return void 0;
   }
 }
@@ -1539,7 +1589,7 @@ async function readSiwxInfo(res) {
       return info;
     }
     return null;
-  } catch (e18) {
+  } catch (e19) {
     return null;
   }
 }
@@ -1619,7 +1669,7 @@ function firstArray(o, ...keys) {
 function hostOf(url) {
   try {
     return new URL(url).hostname;
-  } catch (e19) {
+  } catch (e20) {
     return url;
   }
 }
@@ -1774,7 +1824,7 @@ var PipRailClient = (_class2 = class {
   safeEmit(event) {
     try {
       this.onEvent(event);
-    } catch (e20) {
+    } catch (e21) {
     }
   }
   /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
@@ -1908,9 +1958,15 @@ var PipRailClient = (_class2 = class {
    *
    * Nothing PipRail-hosted: these are third-party open directories. Never throws
    * for a read problem — an index that's down or changed simply contributes
-   * nothing. Honest caveat: index results are cross-scheme (mostly the
-   * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
-   * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+   * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+   * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+   *   resource you registered on x402scan is live there but will NOT appear here; don't
+   *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+   * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+   *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+   * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
+   *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
+   *   `drivers/evm/exact.ts`).
    */
   async discover(opts = {}) {
     const found = await searchOpenIndexes({
@@ -1935,12 +1991,27 @@ var PipRailClient = (_class2 = class {
   }
   /**
    * List a resource you run on the OPEN x402 registries, so agents can find it.
-   * Default target is **402 Index** — one POST, no auth, no signature, no payment
-   * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
-   * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
-   * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
-   * never a throw. An explicit, developer-invoked action; it moves no funds, and
-   * nothing is PipRail-hosted — you're listing on third-party open directories.
+   * Default target is **402 Index** — one POST, no auth, no signature, no payment.
+   * Add `'x402scan'` to also register via SIWX (one wallet signature; EVM + a
+   * Base/Solana rail). Returns one {@link RegisterOutcome} per target — a target the
+   * chain can't satisfy comes back `{ ok:false, detail }`, never a throw. An explicit,
+   * developer-invoked action; it moves no funds, and nothing is PipRail-hosted —
+   * you're listing on third-party open directories.
+   *
+   * **Listing is asynchronous — each outcome carries a `visibility` + `note` so an
+   * agent knows when/where the resource is findable (don't assume `ok:true` means
+   * "searchable now"):**
+   * - **402 Index** → `visibility:'pending-review'`. It probes your URL on submit, then lists it
+   *   PENDING REVIEW — not searchable until approved (verify your domain on 402index.io for instant
+   *   approval), so `discover()` returns nothing for a fresh listing until then. Retry later.
+   * - **x402scan** → `visibility:'live'`, but **`discover()` does NOT read x402scan** — the
+   *   listing is real on x402scan.com yet won't show up in `discover()`. Base/Solana only;
+   *   needs a resolvable input schema (`/openapi.json` or the `extensions.bazaar` block).
+   * - **Bazaar** → `visibility:'not-listable'` for PipRail (it lists only what its facilitator
+   *   settles; PipRail uses none). You can still READ Bazaar via {@link discover} to find others.
+   *
+   * The per-source facts live in {@link DIRECTORY_INFO} (importable) if you'd rather branch
+   * on them before calling.
    */
   async register(url, opts = {}) {
     const targets = _nullishCoalesce(opts.targets, () => ( ["402index"]));
@@ -1979,7 +2050,7 @@ var PipRailClient = (_class2 = class {
         });
       }
     }
-    return outcomes;
+    return outcomes.map(decorateOutcome);
   }
   /**
    * The discovery signer for the bound wallet (its address + a message signer),
@@ -2339,7 +2410,7 @@ var PipRailClient = (_class2 = class {
 function safeBig(s) {
   try {
     return BigInt(s);
-  } catch (e21) {
+  } catch (e22) {
     return 0n;
   }
 }
@@ -2405,7 +2476,7 @@ function railOnNetwork(rail, matches) {
 function hostOf2(url) {
   try {
     return new URL(url).hostname;
-  } catch (e22) {
+  } catch (e23) {
     return url;
   }
 }
@@ -2436,7 +2507,7 @@ async function readInvalidReason(response) {
         detail: typeof body.detail === "string" ? body.detail : ""
       };
     }
-  } catch (e23) {
+  } catch (e24) {
   }
   return null;
 }
@@ -2447,7 +2518,7 @@ async function readBody(res) {
   if (!text) return null;
   try {
     return JSON.parse(text);
-  } catch (e24) {
+  } catch (e25) {
     return text;
   }
 }
@@ -2627,7 +2698,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_register",
-      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
       annotations: {
         title: "Register an x402 endpoint",
         readOnlyHint: false,
@@ -2685,7 +2756,7 @@ async function post(url, body, headers) {
   let json = null;
   try {
     json = await res.json();
-  } catch (e25) {
+  } catch (e26) {
   }
   return { status: res.status, json };
 }
@@ -2939,7 +3010,7 @@ function createPaymentGate(options) {
     if (options.onPaid) {
       try {
         options.onPaid(receipt);
-      } catch (e26) {
+      } catch (e27) {
       }
     }
   }
@@ -3109,7 +3180,7 @@ var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
 function pathOf(url) {
   try {
     return new URL(url).pathname || "/";
-  } catch (e27) {
+  } catch (e28) {
     return url.startsWith("/") ? url : `/${url}`;
   }
 }
@@ -3216,4 +3287,7 @@ function buildX402DnsTxt(input) {
 
 
 
-exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkMDLZJGLYcjs.ConfirmationTimeoutError; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkMDLZJGLYcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkMDLZJGLYcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkMDLZJGLYcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkMDLZJGLYcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkMDLZJGLYcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkMDLZJGLYcjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkMDLZJGLYcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkMDLZJGLYcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkMDLZJGLYcjs.PipRailError; exports.RecipientNotReadyError = _chunkMDLZJGLYcjs.RecipientNotReadyError; exports.SettlementError = _chunkMDLZJGLYcjs.SettlementError; exports.UnknownTokenError = _chunkMDLZJGLYcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkMDLZJGLYcjs.UnsupportedNetworkError; exports.WrongChainError = _chunkMDLZJGLYcjs.WrongChainError; exports.WrongFamilyError = _chunkMDLZJGLYcjs.WrongFamilyError; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.createPaymentGate = createPaymentGate; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.toInsufficientFundsError = _chunkMDLZJGLYcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody;
+
+
+
+exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkMDLZJGLYcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkMDLZJGLYcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkMDLZJGLYcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkMDLZJGLYcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkMDLZJGLYcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkMDLZJGLYcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkMDLZJGLYcjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkMDLZJGLYcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkMDLZJGLYcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkMDLZJGLYcjs.PipRailError; exports.RecipientNotReadyError = _chunkMDLZJGLYcjs.RecipientNotReadyError; exports.SettlementError = _chunkMDLZJGLYcjs.SettlementError; exports.UnknownTokenError = _chunkMDLZJGLYcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkMDLZJGLYcjs.UnsupportedNetworkError; exports.WrongChainError = _chunkMDLZJGLYcjs.WrongChainError; exports.WrongFamilyError = _chunkMDLZJGLYcjs.WrongFamilyError; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.getDirectoryInfo = getDirectoryInfo; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.toInsufficientFundsError = _chunkMDLZJGLYcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody;

package/dist/index.d.cts

@@ -216,9 +216,6 @@ type VerifyResult = {
 declare const HEADER_REQUIRED = "payment-required";
 declare const HEADER_SIGNATURE = "payment-signature";
 declare const HEADER_RESPONSE = "payment-response";
-/** Legacy x402 v1 header names. PipRail EMITS v2 (the constants above) but also
- *  READS the v1 client header and ECHOES the v1 response header, so a deprecated
- *  v1 client (still ~half the installed base) interoperates on the `exact` rail. */
 declare const HEADER_SIGNATURE_V1 = "x-payment";
 declare const HEADER_RESPONSE_V1 = "x-payment-response";
 declare function buildChallengeHeader(challenge: X402Challenge): string;
@@ -4237,6 +4234,14 @@ interface DiscoveredResource {
     /** The payment options the index advertises (best-effort, cross-scheme). */
     rails: DiscoveredRail[];
 }
+/** Where a listing stands after a register attempt — a branchable lifecycle
+ *  state so an agent doesn't have to re-derive each index's behaviour:
+ *  - `'live'`           — findable now (search it immediately).
+ *  - `'pending-review'` — accepted, but the index reviews/propagates before it's
+ *                         publicly findable; allow a short delay before `discover()`.
+ *  - `'not-listable'`   — it didn't list (a failure, or this index structurally
+ *                         can't list a PipRail resource). See `detail` + `note`. */
+type ListingVisibility = 'live' | 'pending-review' | 'not-listable';
 /** The result of trying to list a resource on one open index. */
 interface RegisterOutcome {
     source: DiscoverySource;
@@ -4247,6 +4252,14 @@ interface RegisterOutcome {
     detail?: string;
     /** A link to the listing, when the index returns one. */
     listingUrl?: string;
+    /** The lifecycle state of this listing — `'live'`, `'pending-review'`, or
+     *  `'not-listable'`. Projected from {@link DIRECTORY_INFO}; branch on this
+     *  instead of guessing how soon `discover()` will find the resource. */
+    visibility?: ListingVisibility;
+    /** A one-line, agent-readable caveat for this source (from {@link DIRECTORY_INFO})
+     *  — e.g. "402 Index reviews before publishing" or "discover() doesn't read
+     *  x402scan, so a live listing there won't appear in discover() results". */
+    note?: string;
 }
 interface SearchOpenIndexesOptions {
     /** Free-text query (filtered client-side against name/description/resource). */
@@ -4278,6 +4291,48 @@ interface RegisterInput {
      */
     attribution?: boolean;
 }
+/**
+ * Static, agent-readable lifecycle facts about one open index — the SINGLE source
+ * of truth that {@link RegisterOutcome.visibility}/`note` are projected from, and
+ * that an agent can also query directly (via {@link getDirectoryInfo}) to reason
+ * about an index BEFORE calling. Best-effort: an index can change its behaviour,
+ * so treat the timing as guidance, not an SLA.
+ */
+interface DirectoryInfo {
+    source: DiscoverySource;
+    /** How a new listing is gated: a synchronous URL probe (`402index`, `x402scan`),
+     *  or coupled to a facilitator settling a payment (`bazaar`). */
+    review: 'probe-sync' | 'settle-coupled';
+    /** Auth needed to WRITE a listing. */
+    auth: 'none' | 'siwx' | 'facilitator-only';
+    /** Chains (CAIP-2) this index will list. `null` = any chain the resource advertises. */
+    chains: readonly string[] | null;
+    /** Visibility a SUCCESSFUL listing reaches here (the steady state a non-failed
+     *  outcome maps to). */
+    onSuccess: ListingVisibility;
+    /** Whether THIS SDK's {@link PipRailClient.discover} reads this index. It reads
+     *  `bazaar` + `402index`; it does NOT read `x402scan` — so a live x402scan listing
+     *  won't appear in `discover()` results. Don't read that absence as failure. */
+    readByDiscover: boolean;
+    /** One-line caveat: why a register might fail, or what to expect afterwards. */
+    caveat: string;
+}
+/**
+ * The open directories' lifecycle, as one queryable map. An agent can branch on
+ * this without embedding directory knowledge: `DIRECTORY_INFO[source].readByDiscover`,
+ * `.chains`, `.onSuccess`, etc. {@link PipRailClient.register} projects the relevant
+ * entry onto every {@link RegisterOutcome} (`visibility` + `note`).
+ */
+declare const DIRECTORY_INFO: Readonly<Record<DiscoverySource, DirectoryInfo>>;
+/** Lifecycle facts for one open index (auth, chains, how soon a listing is
+ *  findable, whether `discover()` reads it). See {@link DIRECTORY_INFO}. The param
+ *  is the closed {@link DiscoverySource} union (TS callers are safe); a string
+ *  outside it returns `undefined` at runtime. */
+declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
+/** Project the static {@link DIRECTORY_INFO} lifecycle facts onto a register
+ *  outcome, so an agent gets `visibility` + `note` in the result it already holds —
+ *  no second lookup. A failed outcome is always `'not-listable'`. Idempotent. */
+declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
  *  An unknown slug returns unchanged (no `:`), which the client treats as
@@ -4291,8 +4346,11 @@ declare function normalizeNetwork(network: string): string;
 declare function searchOpenIndexes(opts?: SearchOpenIndexesOptions): Promise<DiscoveredResource[]>;
 /**
  * Register a resource on **402 Index** — the primary, friction-free path: a
- * single POST, no auth, no signature, no payment. Searchable within seconds.
- * Returns a structured outcome; never throws for an HTTP/transport problem.
+ * single POST, no auth, no signature, no payment. A self-registered listing is
+ * **pending review** (not searchable until approved — verify your domain on
+ * 402index.io for instant approval). Returns a structured outcome; never throws
+ * for an HTTP/transport problem. NOTE: the outcome is BARE — `visibility`/`note`
+ * are added by {@link PipRailClient.register} (or call {@link decorateOutcome}).
  */
 declare function register402Index(input: RegisterInput): Promise<RegisterOutcome>;
 /**
@@ -4300,7 +4358,9 @@ declare function register402Index(input: RegisterInput): Promise<RegisterOutcome
  * EIP-4361 challenge with the merchant's own key, resend with the
  * `SIGN-IN-WITH-X` header. Facilitator-free, but **Base/Solana-only** and EVM
  * signing today. EXPERIMENTAL — the open SIWX handshake is a moving convention;
- * validate against x402scan before relying on it. Never throws.
+ * validate against x402scan before relying on it. Never throws. NOTE: returns a
+ * BARE outcome — `visibility`/`note` are added by {@link PipRailClient.register}
+ * (or call {@link decorateOutcome}).
  */
 declare function registerX402Scan(input: {
     url: string;
@@ -4753,19 +4813,40 @@ declare class PipRailClient {
      *
      * Nothing PipRail-hosted: these are third-party open directories. Never throws
      * for a read problem — an index that's down or changed simply contributes
-     * nothing. Honest caveat: index results are cross-scheme (mostly the
-     * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
-     * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+     * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+     * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+     *   resource you registered on x402scan is live there but will NOT appear here; don't
+     *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+     * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+     *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+     * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
+     *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
+     *   `drivers/evm/exact.ts`).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
      * List a resource you run on the OPEN x402 registries, so agents can find it.
-     * Default target is **402 Index** — one POST, no auth, no signature, no payment
-     * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
-     * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
-     * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
-     * never a throw. An explicit, developer-invoked action; it moves no funds, and
-     * nothing is PipRail-hosted — you're listing on third-party open directories.
+     * Default target is **402 Index** — one POST, no auth, no signature, no payment.
+     * Add `'x402scan'` to also register via SIWX (one wallet signature; EVM + a
+     * Base/Solana rail). Returns one {@link RegisterOutcome} per target — a target the
+     * chain can't satisfy comes back `{ ok:false, detail }`, never a throw. An explicit,
+     * developer-invoked action; it moves no funds, and nothing is PipRail-hosted —
+     * you're listing on third-party open directories.
+     *
+     * **Listing is asynchronous — each outcome carries a `visibility` + `note` so an
+     * agent knows when/where the resource is findable (don't assume `ok:true` means
+     * "searchable now"):**
+     * - **402 Index** → `visibility:'pending-review'`. It probes your URL on submit, then lists it
+     *   PENDING REVIEW — not searchable until approved (verify your domain on 402index.io for instant
+     *   approval), so `discover()` returns nothing for a fresh listing until then. Retry later.
+     * - **x402scan** → `visibility:'live'`, but **`discover()` does NOT read x402scan** — the
+     *   listing is real on x402scan.com yet won't show up in `discover()`. Base/Solana only;
+     *   needs a resolvable input schema (`/openapi.json` or the `extensions.bazaar` block).
+     * - **Bazaar** → `visibility:'not-listable'` for PipRail (it lists only what its facilitator
+     *   settles; PipRail uses none). You can still READ Bazaar via {@link discover} to find others.
+     *
+     * The per-source facts live in {@link DIRECTORY_INFO} (importable) if you'd rather branch
+     * on them before calling.
      */
     register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
     /**
@@ -5619,12 +5700,21 @@ declare function buildExactAuthorization(params: BuildExactParams): Promise<{
     authorization: ExactAuthorization;
     signature: Hex;
 }>;
-/** Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value. */
+/**
+ * Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value — the
+ * **v1 flat shape** (`{ x402Version, scheme, network, payload }`). This is a
+ * client-side UTILITY (PipRail's own client pays only `onchain-proof`, never this);
+ * the v1 flat shape is what Coinbase's original reference emits and is still accepted
+ * by every x402 gate + facilitator, so `x402Version` defaults to `1` to stay
+ * INTERNALLY CONSISTENT with that shape (emitting `2` here would mislabel a v1 body —
+ * a proper v2 `exact` payload is the nested `accepted`-envelope shape instead). See
+ * the version-posture note in `x402.ts`.
+ */
 declare function encodeXPaymentHeader(input: {
     network: string;
     authorization: ExactAuthorization;
     signature: Hex;
-    /** x402 envelope version (Coinbase's reference uses 1). */
+    /** x402 envelope version. Defaults to `1` — consistent with this flat shape. */
     x402Version?: number;
 }): string;
 /**
@@ -5740,4 +5830,4 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
     version: string;
 } | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };

package/dist/index.d.ts

@@ -216,9 +216,6 @@ type VerifyResult = {
 declare const HEADER_REQUIRED = "payment-required";
 declare const HEADER_SIGNATURE = "payment-signature";
 declare const HEADER_RESPONSE = "payment-response";
-/** Legacy x402 v1 header names. PipRail EMITS v2 (the constants above) but also
- *  READS the v1 client header and ECHOES the v1 response header, so a deprecated
- *  v1 client (still ~half the installed base) interoperates on the `exact` rail. */
 declare const HEADER_SIGNATURE_V1 = "x-payment";
 declare const HEADER_RESPONSE_V1 = "x-payment-response";
 declare function buildChallengeHeader(challenge: X402Challenge): string;
@@ -4237,6 +4234,14 @@ interface DiscoveredResource {
     /** The payment options the index advertises (best-effort, cross-scheme). */
     rails: DiscoveredRail[];
 }
+/** Where a listing stands after a register attempt — a branchable lifecycle
+ *  state so an agent doesn't have to re-derive each index's behaviour:
+ *  - `'live'`           — findable now (search it immediately).
+ *  - `'pending-review'` — accepted, but the index reviews/propagates before it's
+ *                         publicly findable; allow a short delay before `discover()`.
+ *  - `'not-listable'`   — it didn't list (a failure, or this index structurally
+ *                         can't list a PipRail resource). See `detail` + `note`. */
+type ListingVisibility = 'live' | 'pending-review' | 'not-listable';
 /** The result of trying to list a resource on one open index. */
 interface RegisterOutcome {
     source: DiscoverySource;
@@ -4247,6 +4252,14 @@ interface RegisterOutcome {
     detail?: string;
     /** A link to the listing, when the index returns one. */
     listingUrl?: string;
+    /** The lifecycle state of this listing — `'live'`, `'pending-review'`, or
+     *  `'not-listable'`. Projected from {@link DIRECTORY_INFO}; branch on this
+     *  instead of guessing how soon `discover()` will find the resource. */
+    visibility?: ListingVisibility;
+    /** A one-line, agent-readable caveat for this source (from {@link DIRECTORY_INFO})
+     *  — e.g. "402 Index reviews before publishing" or "discover() doesn't read
+     *  x402scan, so a live listing there won't appear in discover() results". */
+    note?: string;
 }
 interface SearchOpenIndexesOptions {
     /** Free-text query (filtered client-side against name/description/resource). */
@@ -4278,6 +4291,48 @@ interface RegisterInput {
      */
     attribution?: boolean;
 }
+/**
+ * Static, agent-readable lifecycle facts about one open index — the SINGLE source
+ * of truth that {@link RegisterOutcome.visibility}/`note` are projected from, and
+ * that an agent can also query directly (via {@link getDirectoryInfo}) to reason
+ * about an index BEFORE calling. Best-effort: an index can change its behaviour,
+ * so treat the timing as guidance, not an SLA.
+ */
+interface DirectoryInfo {
+    source: DiscoverySource;
+    /** How a new listing is gated: a synchronous URL probe (`402index`, `x402scan`),
+     *  or coupled to a facilitator settling a payment (`bazaar`). */
+    review: 'probe-sync' | 'settle-coupled';
+    /** Auth needed to WRITE a listing. */
+    auth: 'none' | 'siwx' | 'facilitator-only';
+    /** Chains (CAIP-2) this index will list. `null` = any chain the resource advertises. */
+    chains: readonly string[] | null;
+    /** Visibility a SUCCESSFUL listing reaches here (the steady state a non-failed
+     *  outcome maps to). */
+    onSuccess: ListingVisibility;
+    /** Whether THIS SDK's {@link PipRailClient.discover} reads this index. It reads
+     *  `bazaar` + `402index`; it does NOT read `x402scan` — so a live x402scan listing
+     *  won't appear in `discover()` results. Don't read that absence as failure. */
+    readByDiscover: boolean;
+    /** One-line caveat: why a register might fail, or what to expect afterwards. */
+    caveat: string;
+}
+/**
+ * The open directories' lifecycle, as one queryable map. An agent can branch on
+ * this without embedding directory knowledge: `DIRECTORY_INFO[source].readByDiscover`,
+ * `.chains`, `.onSuccess`, etc. {@link PipRailClient.register} projects the relevant
+ * entry onto every {@link RegisterOutcome} (`visibility` + `note`).
+ */
+declare const DIRECTORY_INFO: Readonly<Record<DiscoverySource, DirectoryInfo>>;
+/** Lifecycle facts for one open index (auth, chains, how soon a listing is
+ *  findable, whether `discover()` reads it). See {@link DIRECTORY_INFO}. The param
+ *  is the closed {@link DiscoverySource} union (TS callers are safe); a string
+ *  outside it returns `undefined` at runtime. */
+declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
+/** Project the static {@link DIRECTORY_INFO} lifecycle facts onto a register
+ *  outcome, so an agent gets `visibility` + `note` in the result it already holds —
+ *  no second lookup. A failed outcome is always `'not-listable'`. Idempotent. */
+declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
  *  An unknown slug returns unchanged (no `:`), which the client treats as
@@ -4291,8 +4346,11 @@ declare function normalizeNetwork(network: string): string;
 declare function searchOpenIndexes(opts?: SearchOpenIndexesOptions): Promise<DiscoveredResource[]>;
 /**
  * Register a resource on **402 Index** — the primary, friction-free path: a
- * single POST, no auth, no signature, no payment. Searchable within seconds.
- * Returns a structured outcome; never throws for an HTTP/transport problem.
+ * single POST, no auth, no signature, no payment. A self-registered listing is
+ * **pending review** (not searchable until approved — verify your domain on
+ * 402index.io for instant approval). Returns a structured outcome; never throws
+ * for an HTTP/transport problem. NOTE: the outcome is BARE — `visibility`/`note`
+ * are added by {@link PipRailClient.register} (or call {@link decorateOutcome}).
  */
 declare function register402Index(input: RegisterInput): Promise<RegisterOutcome>;
 /**
@@ -4300,7 +4358,9 @@ declare function register402Index(input: RegisterInput): Promise<RegisterOutcome
  * EIP-4361 challenge with the merchant's own key, resend with the
  * `SIGN-IN-WITH-X` header. Facilitator-free, but **Base/Solana-only** and EVM
  * signing today. EXPERIMENTAL — the open SIWX handshake is a moving convention;
- * validate against x402scan before relying on it. Never throws.
+ * validate against x402scan before relying on it. Never throws. NOTE: returns a
+ * BARE outcome — `visibility`/`note` are added by {@link PipRailClient.register}
+ * (or call {@link decorateOutcome}).
  */
 declare function registerX402Scan(input: {
     url: string;
@@ -4753,19 +4813,40 @@ declare class PipRailClient {
      *
      * Nothing PipRail-hosted: these are third-party open directories. Never throws
      * for a read problem — an index that's down or changed simply contributes
-     * nothing. Honest caveat: index results are cross-scheme (mostly the
-     * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
-     * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+     * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+     * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+     *   resource you registered on x402scan is live there but will NOT appear here; don't
+     *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+     * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+     *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+     * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
+     *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
+     *   `drivers/evm/exact.ts`).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
      * List a resource you run on the OPEN x402 registries, so agents can find it.
-     * Default target is **402 Index** — one POST, no auth, no signature, no payment
-     * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
-     * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
-     * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
-     * never a throw. An explicit, developer-invoked action; it moves no funds, and
-     * nothing is PipRail-hosted — you're listing on third-party open directories.
+     * Default target is **402 Index** — one POST, no auth, no signature, no payment.
+     * Add `'x402scan'` to also register via SIWX (one wallet signature; EVM + a
+     * Base/Solana rail). Returns one {@link RegisterOutcome} per target — a target the
+     * chain can't satisfy comes back `{ ok:false, detail }`, never a throw. An explicit,
+     * developer-invoked action; it moves no funds, and nothing is PipRail-hosted —
+     * you're listing on third-party open directories.
+     *
+     * **Listing is asynchronous — each outcome carries a `visibility` + `note` so an
+     * agent knows when/where the resource is findable (don't assume `ok:true` means
+     * "searchable now"):**
+     * - **402 Index** → `visibility:'pending-review'`. It probes your URL on submit, then lists it
+     *   PENDING REVIEW — not searchable until approved (verify your domain on 402index.io for instant
+     *   approval), so `discover()` returns nothing for a fresh listing until then. Retry later.
+     * - **x402scan** → `visibility:'live'`, but **`discover()` does NOT read x402scan** — the
+     *   listing is real on x402scan.com yet won't show up in `discover()`. Base/Solana only;
+     *   needs a resolvable input schema (`/openapi.json` or the `extensions.bazaar` block).
+     * - **Bazaar** → `visibility:'not-listable'` for PipRail (it lists only what its facilitator
+     *   settles; PipRail uses none). You can still READ Bazaar via {@link discover} to find others.
+     *
+     * The per-source facts live in {@link DIRECTORY_INFO} (importable) if you'd rather branch
+     * on them before calling.
      */
     register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
     /**
@@ -5619,12 +5700,21 @@ declare function buildExactAuthorization(params: BuildExactParams): Promise<{
     authorization: ExactAuthorization;
     signature: Hex;
 }>;
-/** Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value. */
+/**
+ * Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value — the
+ * **v1 flat shape** (`{ x402Version, scheme, network, payload }`). This is a
+ * client-side UTILITY (PipRail's own client pays only `onchain-proof`, never this);
+ * the v1 flat shape is what Coinbase's original reference emits and is still accepted
+ * by every x402 gate + facilitator, so `x402Version` defaults to `1` to stay
+ * INTERNALLY CONSISTENT with that shape (emitting `2` here would mislabel a v1 body —
+ * a proper v2 `exact` payload is the nested `accepted`-envelope shape instead). See
+ * the version-posture note in `x402.ts`.
+ */
 declare function encodeXPaymentHeader(input: {
     network: string;
     authorization: ExactAuthorization;
     signature: Hex;
-    /** x402 envelope version (Coinbase's reference uses 1). */
+    /** x402 envelope version. Defaults to `1` — consistent with this flat shape. */
     x402Version?: number;
 }): string;
 /**
@@ -5740,4 +5830,4 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
     version: string;
 } | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };

package/dist/index.js

@@ -1305,6 +1305,42 @@ async function resolveNetwork2(opts) {
 }
 
 // src/indexes.ts
+var DIRECTORY_INFO = {
+  "402index": {
+    source: "402index",
+    review: "probe-sync",
+    auth: "none",
+    chains: null,
+    onSuccess: "pending-review",
+    readByDiscover: true,
+    caveat: "402 Index probes your URL on submit, then lists it as PENDING REVIEW \u2014 a self-registered resource is NOT in search until approved. Verify your domain on 402index.io for instant approval; otherwise it appears after manual review, so retry discover() later."
+  },
+  x402scan: {
+    source: "x402scan",
+    review: "probe-sync",
+    auth: "siwx",
+    chains: ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
+    onSuccess: "live",
+    readByDiscover: false,
+    caveat: "x402scan lists Base/Solana only, needs one wallet signature (SIWX), and requires a resolvable input schema (from /openapi.json or the bazaar extension in the 402 body). It goes live on x402scan.com immediately on success \u2014 but discover() does NOT read x402scan, so the listing won't appear in discover() results."
+  },
+  bazaar: {
+    source: "bazaar",
+    review: "settle-coupled",
+    auth: "facilitator-only",
+    chains: null,
+    onSuccess: "not-listable",
+    readByDiscover: true,
+    caveat: "CDP Bazaar has no register endpoint \u2014 it catalogs a resource only when its own facilitator settles a payment. PipRail verifies locally with no facilitator, so a PipRail resource cannot be listed here (you can still READ Bazaar to find others). List on 402 Index or x402scan instead."
+  }
+};
+function getDirectoryInfo(source) {
+  return DIRECTORY_INFO[source];
+}
+function decorateOutcome(o) {
+  const info = DIRECTORY_INFO[o.source];
+  return { ...o, visibility: o.ok ? info.onSuccess : "not-listable", note: info.caveat };
+}
 var BAZAAR_URL = "https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources";
 var INDEX402_SEARCH = "https://402index.io/api/v1/services";
 var INDEX402_REGISTER = "https://402index.io/api/v1/register";
@@ -1457,7 +1493,13 @@ async function register402Index(input) {
       body: JSON.stringify(payload)
     });
     if (res.ok) {
-      return { source: "402index", ok: true, status: res.status, detail: "Listed on 402 Index (searchable at 402index.io)." };
+      const msg = await readIndexMessage(res);
+      return {
+        source: "402index",
+        ok: true,
+        status: res.status,
+        detail: msg ?? "Registered on 402 Index \u2014 pending review (verify your domain on 402index.io for instant approval)."
+      };
     }
     const why = await readIndexError(res);
     return {
@@ -1470,6 +1512,14 @@ async function register402Index(input) {
     return { source: "402index", ok: false, detail: errMsg(err) };
   }
 }
+async function readIndexMessage(res) {
+  try {
+    const body = await res.json();
+    return typeof body.message === "string" && body.message.length > 0 ? body.message : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function readIndexError(res) {
   try {
     const body = await res.json();
@@ -1908,9 +1958,15 @@ var PipRailClient = class {
    *
    * Nothing PipRail-hosted: these are third-party open directories. Never throws
    * for a read problem — an index that's down or changed simply contributes
-   * nothing. Honest caveat: index results are cross-scheme (mostly the
-   * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
-   * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+   * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+   * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+   *   resource you registered on x402scan is live there but will NOT appear here; don't
+   *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+   * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+   *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+   * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
+   *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
+   *   `drivers/evm/exact.ts`).
    */
   async discover(opts = {}) {
     const found = await searchOpenIndexes({
@@ -1935,12 +1991,27 @@ var PipRailClient = class {
   }
   /**
    * List a resource you run on the OPEN x402 registries, so agents can find it.
-   * Default target is **402 Index** — one POST, no auth, no signature, no payment
-   * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
-   * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
-   * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
-   * never a throw. An explicit, developer-invoked action; it moves no funds, and
-   * nothing is PipRail-hosted — you're listing on third-party open directories.
+   * Default target is **402 Index** — one POST, no auth, no signature, no payment.
+   * Add `'x402scan'` to also register via SIWX (one wallet signature; EVM + a
+   * Base/Solana rail). Returns one {@link RegisterOutcome} per target — a target the
+   * chain can't satisfy comes back `{ ok:false, detail }`, never a throw. An explicit,
+   * developer-invoked action; it moves no funds, and nothing is PipRail-hosted —
+   * you're listing on third-party open directories.
+   *
+   * **Listing is asynchronous — each outcome carries a `visibility` + `note` so an
+   * agent knows when/where the resource is findable (don't assume `ok:true` means
+   * "searchable now"):**
+   * - **402 Index** → `visibility:'pending-review'`. It probes your URL on submit, then lists it
+   *   PENDING REVIEW — not searchable until approved (verify your domain on 402index.io for instant
+   *   approval), so `discover()` returns nothing for a fresh listing until then. Retry later.
+   * - **x402scan** → `visibility:'live'`, but **`discover()` does NOT read x402scan** — the
+   *   listing is real on x402scan.com yet won't show up in `discover()`. Base/Solana only;
+   *   needs a resolvable input schema (`/openapi.json` or the `extensions.bazaar` block).
+   * - **Bazaar** → `visibility:'not-listable'` for PipRail (it lists only what its facilitator
+   *   settles; PipRail uses none). You can still READ Bazaar via {@link discover} to find others.
+   *
+   * The per-source facts live in {@link DIRECTORY_INFO} (importable) if you'd rather branch
+   * on them before calling.
    */
   async register(url, opts = {}) {
     const targets = opts.targets ?? ["402index"];
@@ -1979,7 +2050,7 @@ var PipRailClient = class {
         });
       }
     }
-    return outcomes;
+    return outcomes.map(decorateOutcome);
   }
   /**
    * The discovery signer for the bound wallet (its address + a message signer),
@@ -2627,7 +2698,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_register",
-      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
       annotations: {
         title: "Register an x402 endpoint",
         readOnlyHint: false,
@@ -3161,6 +3232,7 @@ function buildX402DnsTxt(input) {
 export {
   CHAINS,
   ConfirmationTimeoutError,
+  DIRECTORY_INFO,
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
   GENERATOR,
@@ -3194,9 +3266,11 @@ export {
   buildX402DnsTxt,
   chainIdForExactNetwork,
   createPaymentGate,
+  decorateOutcome,
   eip3009Abi,
   encodeXPaymentHeader,
   evaluatePolicy,
+  getDirectoryInfo,
   normalizeNetwork,
   parseChallenge,
   parseExactPaymentHeader,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",