[upstream-ready] sk-016: agentic-payments MPP discovery layer

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot, on behalf of @kaankacar.

Finding ID

sk-016

Raven source record

https://github.com/stellar-experimental/stellar-raven/blob/main/improvements/skills/sk-016-agentic-payments-mpp-discovery-gap.md

Commit-pinned snapshot: https://github.com/stellar-experimental/stellar-raven/blob/dbc466e551053d262ea4ee4267a09a6526124396/improvements/skills/sk-016-agentic-payments-mpp-discovery-gap.md

Resolving upstream work

• Issue: The agentic-payments MPP guide omits the MPP discovery layer stellar/stellar-dev-skill#107
• PR: Add the MPP discovery layer to the agentic-payments skill stellar/stellar-dev-skill#109
• Merge commit: stellar/stellar-dev-skill@1f4b94e

skills/agentic-payments/mpp.md gets a ## Discovery section covering all four recommended points. skills/agentic-payments/SKILL.md routes a seller to it from both decision tables. Two discovery pitfalls were added, and the mppx/express row in the imports table now names discovery().

Deployment evidence

Merged to main at 2026-08-19T20:57:20Z as 1f4b94e.

Deployed to https://skills.stellar.org. Site build run: https://github.com/stellar/stellar-dev-skill/actions/runs/32301336373 (completed 2026-08-19T20:58:15Z). Pages deployment completed just after it.

Smallest live recheck

1. curl -s https://skills.stellar.org/skills/agentic-payments/mpp.md
2. Confirm the heading ## Discovery: let agents find your paid API is present.
3. Confirm the four points:
   • An OpenAPI 3.1 document at GET /openapi.json, with an x-payment-info extension holding an offers[] array, and the discovery() call from mppx/express.
   • "The runtime 402 Challenge is authoritative for price, token, network, expiry, and terms."
   • MPPScan and the MPP services directory as optional registrations, plus the link https://mpp.dev/mcp/services.
   • "A registry listing advertises your service. It does not verify any client payment."
4. curl -s https://skills.stellar.org/skills/agentic-payments/SKILL.md and confirm two links to mpp.md#discovery-let-agents-find-your-paid-api.

I ran all four steps after the deploy. All passed.

Notes on verification

I checked the four points against https://mpp.dev/advanced/discovery.

I also checked the API against the published package, not only the docs page. mppx@0.6.31 is the version that @stellar/mpp@0.7.1 resolves to through its mppx: ^0.6.29 peer range. dist/middlewares/express.d.ts declares discovery(app, mppx, config?). dist/middlewares/express.js mounts config.path ?? '/openapi.json' and passes config.routes ?? [] to generate(). dist/discovery/OpenApi.js emits openapi: '3.1.0' and sets x-payment-info. HandlerRouteConfig is { handler, method, path }, which is the shape the example uses. dist/cli/cli.js defines discover validate and accepts a URL. The same express.d.ts is byte-identical in mppx@0.8.17.

The Express adapter has no auto option, so it documents only the routes listed in routes. The second added pitfall states that.

Verification contract

• I linked the exact Raven finding and the resolving upstream work.
• I understand Raven will independently recheck the live surface, then a distinct reviewer must repeat the trigger before the active finding is retired to the resolved ledger.
• This report contains no credentials, private partner-tier details, or other secrets.

[kalepail]

Commit 5f31ad2 retires sk-016 after a fresh trigger check and independent review.

Resolved receipt: https://github.com/stellar-experimental/stellar-raven/blob/5f31ad22bb64783e636430fffed483d00fa63328/improvements/resolved.json

Commit: 5f31ad2