[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 (only a create scaffold command). 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 by wrapping the SDK's own x402Serve() (don't reimplement verification/settlement) 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 (initX402/x402Fetch) and x402Serve() — keep @x402/* versions aligned with the SDK.
• The credential header the client must send after a 402 is PAYMENT-SIGNATURE — not X-PAYMENT (x402 v1). Several past submissions on this repo got this wrong; the SDK's own client already handles it correctly, so lean on it rather than hand-rolling the flow.

Test target (live, verified)

Pay against Nirium's own live testnet x402 endpoint — confirmed responding today:

GET https://nirium-agent.fly.dev/api/v1/premium/signals

Returns a real 402 with a payment-required header (x402 v2, stellar:testnet, 0.02 USDC, fees sponsored). No API key needed. This is the same endpoint referenced in the SDK's own README examples.

Out of scope

• MPP support in the CLI (x402 only for this issue).
• A GUI — terminal only.

References

• Dev docs: https://nirium.xyz/developers
• This repo's README: https://github.com/nirium-protocol/nirium-sdk/blob/main/README.md
• Contributing guide (how the GrantFox apply/assign flow works here): https://github.com/nirium-protocol/nirium-sdk/blob/main/CONTRIBUTING.md
• TypeScript SDK (npm): https://www.npmjs.com/package/nirium
• CLI (npm): https://www.npmjs.com/package/nirium-cli
• MCP server (npm): https://www.npmjs.com/package/nirium-mcp
• Questions: comment directly on this issue — there's no separate community chat for this repo yet.

Reward

Eligibility is subject to GrantFox review under this campaign. Rewards are decided by GrantFox based on quality and available budget and are not guaranteed.

[M0nsxx]

I'll add two commands to the existing CLI: nirium pay that reuses the SDK's own x402 client (initX402/x402Fetch) rather than re-implementing the flow, and nirium serve that wraps x402Serve() locally so pay has something real to test against. Secrets come from env only and are never printed or logged. I'll prove it end-to-end against the real testnet facilitator with an actual tx hash in the PR. ETA: 4-5 days.

[grantfox-oss]

🦊 GrantFox — @M0nsxx has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #44)
2. Your PR will be reviewed by the nirium-protocol maintainers

Good luck! Track your progress on GrantFox.

[Eras256]

Merged via #62 (feat/cli-pay-serve) — commit history at #62, verified from a clean install with 16/16 tests passing. Thanks @M0nsxx for the persistence through the TS5097 build issue.