API contract

STELLAR_NETWORK=stellar:testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
HORIZON_URL=https://horizon-testnet.stellar.org
NETWORK_PASSPHRASE=Test SDF Network ; September 2015

ISSUER_SECRET=S...        # issues the SXT SEP-41 test asset
ISSUER_PUBLIC=G...
ASSET_CODE=SXT
ASSET_SAC=C...            # SAC contract id — this is `asset` in PaymentRequirements

SELLER_SECRET=S...        # payTo account (has SXT trustline)
SELLER_PUBLIC=G...

PAYER_SECRET=S...         # the agent's wallet (has SXT trustline + balance)
PAYER_PUBLIC=G...

FEEPAYER_SECRET=S...      # facilitator sponsors network fees (RFP 3.1 areFeesSponsored)
FEEPAYER_PUBLIC=G...

FACILITATOR_URL=http://localhost:4021
INDEX_URL=http://localhost:4022
SELLER_URL=http://localhost:4023

export function createCatalog()                    // -> Catalog
// Catalog:
//   upsert(record) -> { ok: boolean, dropped: string[], reason?: string }
//   list({ type, payTo, scheme, network, extensions, limit=20, offset=0 }) -> { items, total, limit, offset }
//   search({ query, limit=20, cursor, ...filters }) -> { items, partialResults, pagination:{limit,cursor} }
//   NOTE: both return INTERNAL records. The wire projection happens in discovery.mjs.
//   size() -> number
export function validateResourceBlock(block)       // soft-drop -> { value, dropped: string[] }
export function validateRouteTemplate(t)           // -> { valid: boolean, reason?: string }
export function scoreHybrid(query, docs)           // BM25 + field-boost -> ranked docs

{
  id: string,                 // `${resource.url}` or `${resource.url}#${input.toolName}` for MCP
  resource: { url, serviceName?, tags?, iconUrl?, description? },
  type: "http" | "mcp",
  network: "stellar:testnet",
  scheme: "exact",
  payTo: "G...",
  asset: "C...",
  maxAmountRequired: "10000",
  extra?: object,             // sanitized accepts.extra of the offering mirrored above
  requirements: [             // EVERY distinct offering this resource advertises.
    { scheme, network, payTo, asset, maxAmountRequired, extra? }
    // Identity = scheme|network|asset|payTo|canonical(extra): re-seeing an offering
    // updates its price in place; a different offering (second upto profile, exact
    // alongside upto) is appended. Top-level fields mirror the most recently seen
    // offering. Content-keyed on purpose until the spec names the discriminator
    // (extra.uptoProfile is still in open upstream PRs) — see issue #1.
  ],
  input: { type, method?, queryParams?, body?, toolName?, inputSchema? },
  output: { type, format?, example? },
  routeTemplate?: string,
  extensions: ["bazaar"],
  lastSeenAt: number,         // ms epoch
  settlements: number         // count of observed settled payments
}

{
  // ---- spec DiscoveryResource ----
  resource: "https://api.example/v1/thing",   // a URL STRING, not the block above
  type: "http" | "mcp",
  x402Version: 2,
  accepts: [                                  // x402 v2 PaymentRequirements — one entry
    { scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra }
    // per distinct offering the record advertises. accepts[0] is always the offering
    // the native mirrors below track; further offerings follow in first-seen order.
  ],
  lastUpdated: "2026-08-07T12:00:00.000Z",    // ISO 8601, from lastSeenAt
  serviceName?, description?, tags?, iconUrl?, mimeType?,   // TOP LEVEL, not nested
  extensions: { bazaar: { info: { input, output }, routeTemplate?, schema? } },  // object MAP

  // ---- additive, STELLARSIGHT-native: not spec, ignored by a spec consumer ----
  id, network, scheme, payTo, asset, maxAmountRequired,     // mirrors of accepts[0]
  input, output, routeTemplate,
  lastSeenAt, firstSeenAt, settlements, seeded,
  _score, _explain
}