[Advanced] nirium CLI: 'pay' and 'serve' commands for x402

[Eras256]

Difficulty: Advanced (senior · 7/10). ~12–18h. Node/TypeScript CLI, Stellar keypair handling, x402.

Context

packages/cli is currently minimal. Developers want to (a) pay an x402-protected endpoint straight from the terminal and (b) spin up a protected endpoint to test against — without writing code. Both belong in the existing nirium CLI.

Goal

Two new commands in the existing nirium CLI, fully typed and tested.

Scope / Deliverables

1. nirium pay <url> [--amount] [--network] — reads the 402 payment requirements, signs the Stellar auth entry from a configured secret, performs the pay→retry, and prints the response plus a tx reference.
2. nirium serve --price --pay-to [--port] — starts a local x402-protected demo endpoint (reuse the SDK server helper) so a developer can test pay against it.
3. Config & safety: secret via env or a nirium config store; the secret is never printed; actionable errors on misconfig.
4. --help for both commands with examples; clean, scriptable output.
5. Tests: argument parsing + the full 402 flow with the network mocked.
6. Update the CLI README.

Acceptance criteria

• nirium pay works end-to-end on testnet against a real facilitator (include a tx hash that resolves on stellar.expert in the PR).
• No secret leakage in logs or output; typed public surface; lint/CI pass.

Pointers

• Extend packages/cli; reuse the SDK's x402 client; keep @x402/* versions aligned with the SDK.

Reward

Eligibility is subject to GrantFox review after the campaign (Official Campaign | FWC26). Rewards are decided by GrantFox based on quality and available budget and are not guaranteed.

[Phantomcall]

I'd like to take this on. I have experience building TypeScript CLIs, integrating Stellar wallets and signing flows, and working on payment infrastructure where developer experience, security, and reliable automation are key. I've built CLI tooling around blockchain SDKs and understand the importance of producing commands that are both scriptable and safe.

For this issue, I'll extend the existing packages/cli with two production-ready commands: nirium pay and nirium serve. The pay command will discover x402 payment requirements from the target endpoint, securely load the configured Stellar secret from the environment or Nirium's configuration store, sign the required authorization entry using the existing SDK, execute the payment→retry flow, and present a clean, script-friendly response including the transaction reference. The implementation will ensure secrets are never logged or exposed, with clear validation and actionable error messages for missing configuration, unsupported networks, or payment failures.

For nirium serve, I'll build a local x402-protected demo server by reusing the existing SDK server helper rather than duplicating payment logic. The command will support configurable pricing, recipient address, and port, making it easy for developers to spin up a protected endpoint and immediately test it using nirium pay.

I'll also add comprehensive --help documentation with practical examples, update the CLI README, and write tests covering argument parsing, configuration loading, security-sensitive paths, and the complete mocked x402 payment flow. The public command surface will remain fully typed and consistent with the existing CLI architecture.

Before submitting the PR, I'll verify the implementation end-to-end against a real Testnet facilitator, include a transaction hash that resolves on stellar.expert, and ensure linting, tests, and CI all pass cleanly.

GitHub: @PHANTOM_CALL