Consolidate x402-stellar and stellar-mpp-sdk under an `agentic-payments` monorepo

[marcelosalloum]

The MPP SDK and this repo (x402-stellar) implement two payment protocols that are conceptually very similar — both are machine-payable HTTP payment flows built on Stellar. In practice, a significant portion of the logic between the two codebases is near-identical copy/paste: transaction construction, fee-bump handling, facilitator patterns, Soroban auth, and wallet interaction flows.

Keeping them as separate repos creates ongoing friction: every improvement to shared logic (bug fixes, performance, new Stellar SDK versions) must be applied twice, and it's easy for the two implementations to drift out of sync. A unified agentic-payments monorepo would eliminate the duplication, enforce feature parity by making shared code literally shared, and give contributors a single place to work across both protocols.

Current State

flowchart LR
    subgraph stellar["stellar org"]
        A["stellar/x402-stellar\n(x402 protocol + facilitator\n+ paywall middleware)"]
        B["stellar/stellar-mpp-sdk\n(MPP SDK)"]
    end

    style A fill:#ffcccc,stroke:#ff0000
    style B fill:#ffcccc,stroke:#ff0000

Loading

Legend:

• Red = Current state (separate repos, duplicated tooling)

Proposed State

flowchart LR
    subgraph mono["stellar/agentic-payments (monorepo)"]
        C["packages/x402-stellar\n(x402 facilitator + middleware)"]
        D["packages/stellar-mpp-sdk\n(MPP SDK)"]
        E["packages/shared\n(common Stellar utils)"]
        F["examples/\n(unified examples)"]
    end

    style C fill:#ccffcc,stroke:#00ff00
    style D fill:#ccffcc,stroke:#00ff00
    style E fill:#ccffcc,stroke:#00ff00
    style F fill:#ccffcc,stroke:#00ff00

Loading

Legend:

• Green = Proposed state (unified monorepo)

Motivation

• MPP and x402 share significant copy/paste logic today: transaction construction, fee-bump handling, facilitator patterns, Soroban auth, and wallet interaction flows
• Any bug fix or improvement to shared logic must currently be applied to both repos separately — they will inevitably drift
• A shared packages/shared (or packages/stellar-core) would make that logic canonical; both protocols build on top of it
• Feature parity is automatic when code is shared, not a manual synchronization exercise
• Both repos use the same toolchain (pnpm workspaces, turbo, TypeScript, vitest) — consolidation has no tooling cost

Proposed Steps

1. Create a new stellar/agentic-payments repository with pnpm monorepo structure
2. Migrate x402-stellar packages into packages/x402-stellar/
3. Migrate stellar-mpp-sdk into packages/stellar-mpp-sdk/
4. Extract common logic into packages/shared/
5. Archive or redirect the original repos with notices pointing to the monorepo
6. Update all npm package names if needed (semver major if breaking)