Merchants — start here

Path B: catalog price format

When the AstraSync bridge pulls your catalog (via discover_catalog), it normalises each SKU's price into the authoritative amount used to price checkouts. This is an integrity path — the bridge prices from yourcatalog, never the agent's claim — so emit the canonical shape below for zero ambiguity.

Canonical (recommended) — emit all three:

{
  "id": "sku-001",
  "title": "Widget",
  "price": { "amount": "7.00", "amount_cents": 700, "currency": "USD" },
  "availability": "in_stock"
}

// Zero-decimal currency (JPY) — no subunit:
{ "price": { "amount": "700", "amount_cents": 700, "currency": "JPY" } }

amount = decimal string in major units; the integer field (amount_cents or Stripe unit_amount) = minor units; currency = ISO 4217.

Also accepted (safety net):

• object aliases: value (≡ amount), price_cents / unit_amount (≡ amount_cents)
• a scalar price — "7.00" or 7 — read as major unitswith the SKU's top-level currency (a bare scalar cannot signal cents; use amount_cents for minor units)
• top-level amount_cents/unit_amount when there is no price object

Fail-closed: if a SKU's price can't be parsed into an authoritative amount, that SKU's checkout is refused with sku_price_unparseable (distinct from sku_not_found) — the bridge never falls back to a caller-supplied price. The accepted shapes are a compatibility net; emit the canonical shape so pricing is never ambiguous.

Settlement: do not fulfill on a placeholder

confirm_purchase today returns a non-settling placeholder and does not yet verify the payment-mandate signature(it checks the mandate's amount/currency against the authoritative total only). No money moves until the payment harness ships. Do not fulfill irreversibly on it.

Gate fulfilment on the explicit top-level settlement state, never on success alone (success: true means the confirm operation succeeded — verification granted — not that payment was captured) and never on the presence of a receipt or txHash:

{
  "success": true,
  "settled": false,
  "settlementStatus": "unsettled_placeholder",
  "txHash": "astrasync-placeholder:...",
  "txHashKind": "astrasync-correlation-placeholder"
}
// Fulfil only when:  settled === true  (settlementStatus: "settled")

Pre-harness, settled is always false. When the harness lands it flips to true with a real txHash. Relatedly, the commerce.payment.mandate_invalid denial dimension fires on amount/currency only today; signature-invalid joins it when the harness lands — do not assume signature validation exists yet.

git clone https://github.com/AstraSync-KYA/KYA-Platform.git
cd KYA-Platform/examples/express-verification-gateway
cp .env.example .env  # then set ASTRASYNC_API_KEY
npm install
npm start             # listens on :4001

The SDK route-pattern matcher is now case-insensitive by default in v2.4.13+ (audit F-A6-31). For belt-and-braces defense — especially if you're running an older SDK version or a mixed-edge setup — set Express to reject mixed-case path variants at the router layer too:

// app.ts (mount BEFORE you load the verification-gateway middleware)
app.set('case sensitive routing', true);
app.set('strict routing', true);

With these set, requests like GET /api/ADMIN/usersreturn 404 from Express before the gateway middleware is consulted — closes the bypass class even on SDK versions where the matcher hasn't been updated.

Staging and production share the same request and response shapes — promoting a tested integration is a single config change.

Swap the host segment (staging.astrasync.ai ↔ astrasync.ai). Everything else — path shape, request bodies, response schemas, error envelopes — is identical. SDK config stays the same.

GET /api/docs/openapi.json serves a tier-filtered view. Anonymous callers see the public-tier subset (~15 paths: auth, registration, verify-access). Pass Authorization: Bearer kya_… to get the paths your tier can actually call (endpoint CRUD, allowlist management, agent CRUD, etc.).

The response stamps x-astrasync-tier-available-counts on the root so you can see at a glance how many additional paths your tier is missing — e.g. if you see customer-admin: 18 and you're unauthenticated, that's 18 paths waiting behind your API key.

Empty allowlist = open (round-12 default flip). Verified agents proceed to PDLSS / trust-score / attestation gates. To CONSTRAIN access, populate the allowlist with explicit owner identifiers — only listed owners can call the endpoint, everyone else is denied at the allowlist gate before downstream evaluation.

POST /api/endpoints/{id}/allowlist accepts these body fields:

Full schema in the authenticated OpenAPI spec — GET /api/docs/openapi.json with your Authorization: Bearer kya_… header.

When a denial response carries a failures[].dimension starting with pdlss. (e.g. pdlss.action, pdlss.scope.resources, pdlss.selfInstantiation) the agent's PDLSS doesn't cover the request. The agent needs to update its PDLSS — see Updating an agent's PDLSS for the two-step retire+re-register recovery workflow available today via the Agent dashboard.

Denial dimensions to recognise on your side:

• pdlss.* — agent-policy failure; recovery is on the agent side (retire+re-register with broader PDLSS).
• counterparty.allowlist— agent isn't in your endpoint's allowlist; you add them (or the endpoint owner does).
• counterparty.trust— agent's trust score below your endpoint's requirement; the agent needs to accrue trust signals (or you lower the threshold).
• attestation.* — agent or owner missing a required attestation (e.g. verified_human_party); complete the attestation flow.
• pdlss.limits.hard_limit_required— the agent declared no Hard Limit (per-transaction ceiling), so it can't transact value. A configuration issue, not an overspend — the agent re-registers with a Hard Limit.
• commerce.intent.approval_required— the value is in the approval band (≥ Autonomous Limit, < Hard Limit) and needs human approval, which isn't wired yet, so it is blocked. NOTE: this is an allowed-but-escalate outcome — policyAllowed stays true. Gate on recommendation / requiresApproval, never admit a request on policyAllowed alone. The SDK middleware already fails closed on this; bridge confirm_purchase returns settlementStatus: blocked_step_up_required with no receipt.

Optional: counterpartyId pins the SDK to a specific ASTRAE-id (use it when one merchant operates multiple endpoints under the same origin). disableInitChecks skips the startup HEAD probe (handy in tests).