Net Payments SDK (x402-native)

net-payments is not a payment processor. It does not custody funds,
process payments, issue invoices, determine taxes, or clear transactions.
x402 v2 moves the money; Net signs the commercial facts around it —
provider identity, discovery-time pricing, tiered verification, immutable
billing, and spend policy.

Before you write or edit any payment code, read concepts.md in this skill
directory. It is the conceptual prerequisite for everything else. The API
templates will look like a dozen payment SDKs and you will write something that
compiles, runs, and is a rejected PR — because the constraints here
(non-custodial, byte-preserved x402, no parallel wire format, tiers not
booleans) are not the constraints of a normal payments library.

How to use this skill

Load reference files on demand — do not read them all up front.

TL;DR mental model (the absolute minimum)

If you remember nothing else from concepts.md, remember these:

1. x402 is the payment wire; Net signs around it. Net envelopes wrap x402
   structures; they never replace, translate, or re-encode them. Chain
   specifics live in x402 schemes + facilitator config — never in Net core.
2. Byte-preservation is law. x402 documents are carried as base64 of their
   original bytes (X402Carry), never re-serialized through Net types.
   Re-serializing a received x402 doc (envelope drift) is a rejected PR.
3. Non-custodial by construction. Identity keys ≠ settlement keys. The
   SchemeSigner takes typed operations and returns signatures; there is no
   raw-bytes signing method and no way for a binding or agent to reach a key.
4. Verification is a tier, not a boolean: observed | confirmed(n) | final. A facilitator receipt is observed, full stop — confirmed(n)
   and final come only from the independent on-chain ChainChecker, so the
   facilitator is never in the trust root. Reorg is a first-class outcome that
   freezes the quote; billing events are immutable.
5. The policy engine decides, not the model. Spend policy runs caller-side
   before anything leaves; provider policy runs at quote issuance and
   re-checks before the handler. Handlers never see unpaid calls. Approvals
   render in UX; the decision lives in shared policy state.
6. Enabling a network is config, not code. Facilitator pack + registry
   entries + a conformance run — no new envelope types, no core changes, no
   per-network branches outside src/x402/.
7. The engine store is bookkeeping; the billing log is the record. Terminal
   quote records are compacted 6h past quote expiry by default, so
   engine.status() returns None for a payment that completed fine — build
   reconciliation on the billing stream. Replay protection is never compacted:
   settlement-transaction tombstones are permanent at every setting, and nothing
   unredeemed or frozen is retired. The horizon is also your re-verification
   window; if you re-verify out of band, widen it or pass None.

The category line, verbatim: Net standardizes the commercial facts around
capability invocation; it does not intermediate the money.

If the user's language conflicts with any of these ("Net wallet", "generate an
invoice", "sign these bytes", "translate x402", "the facilitator confirmed
finality", "auto-refund the overpayment"), stop and read gotchas.md — they're
carrying a mental model that produces compiling-but-rejected code.

Workflow when integrating

1. Select the binding, then load exactly one — and answer "is there a payments
   API at all" before anything else. Payments is a three-binding subsystem.
   • Read the language off the project: Cargo.toml → Rust, package.json
     → Node/TS, pyproject.toml or requirements.txt → Python, go.mod → Go,
     Makefile/CMakeLists.txt beside .c/.h → C.
   • Rust, Python and Node/TS have a full native demand + supply flow.
     Go and C have no payments API at all — not partial, not reduced. Go has
     a golden-vector conformance test and nothing else; C does not even have
     that. If the task is "add x402 payments to our Go service", that is a
     language choice or a feature request, not a coding task. Say so first.
   • Then read bindings.md (routing) and exactly one companion —
     bindings/rust.md, bindings/typescript.md, bindings/python.md,
     bindings/go.md, bindings/c.md. bindings/coverage.md is the
     per-operation matrix and the authoritative answer to "does this language
     have X".
   • Payments is not in the ergonomic wrapper. Neither @net-mesh/sdk nor
     net_sdk contains a line of it. Every payments symbol in Node and Python
     is in @net-mesh/core and net respectively, and there is no
     @net-mesh/payments package. An import from the wrapper fails in a way
     that looks like a missing feature.
   • Never default to Rust because the substrate is Rust. With no project
     context and no language named, ask — the answer decides whether there is
     any code to write.
2. Read concepts.md if this is your first invocation this session.
3. Which side is the user on?
   • Charging for a capability (provider) → provider.md. Price at publish
     (net.pricing.terms@1), run the PaymentEngine lifecycle, pass a
     PaymentFlow into gated_invoke so the payment gate runs before the
     handler.
   • Paying to invoke (caller) → caller.md. CallerPaymentFlow over a
     ProviderChannel, spend policy, the approval loop; branch on the
     net.payment.failure@1 schematic that rides a denial (failure-schematic.md).
   • Paying an external x402 HTTP API → http402.md (X402HttpFlow /
     PaymentHttpClient).
   • Charging for, or buying, an agent task → a2a.md. Paid A2A is
     prepare → purchase → submit, not a one-shot invoke: the same engine must
     sit behind serve_payments and the admission gate, and the caller's
     attempt is durable on disk. Rust and Python only, both directions.
4. Pick the facilitator. Default to MockFacilitator (the conformance
   backbone) for anything not touching real money; HttpFacilitator + a
   config pack for a real network. facilitator.md.
5. Set the required tier. Receipt-trust (observed) or an independent
   check (confirmed(n)/final via ChainChecker)? verification.md.
6. Wire the signer if settling on a real network — ExternalSigner
   (eip155/EIP-3009; key never in Net), ExternalSvmSigner (solana/SPL,
   intent-in/blob-out), or ExternalXrplSigner (xrpl/presigned Payment blob),
   registered per namespace; DevLocalSigner for testnet only (behind
   unsafe-dev-signer). From Python, all three ride the payment_signer*
   kwargs. signer.md.
7. Configure spend policy — limits, allowed networks/assets, the approval
   surface. Real networks deny by default. spend-policy.md.
8. Enabling a new network? It's config + registry + conformance, never
   code. networks.md.
9. Surface billing via BillingLog (stream/export). billing.md.
10. Test against golden vectors + the mock conformance suite; keep the
    key-invariant negative test green. testing.md.
11. Before merging, run the change past the review invariant in
    gotchas.md — most payments mistakes are scope violations, not bugs.
12. If you're unsure about an API, read the source — it's ground truth:
    • Rust core: net/crates/net/payments/src/ (engine/, flow/,
      facilitator/, core/, x402/, policy/, checker/, billing/)
    • Failure schematic (SDK wire object): net/crates/net/sdk/src/tool_payment.rs
    • Rust examples/tests: payments/examples/, payments/tests/
    • Python surface: net/crates/net/bindings/python/src/capability_gateway.rs,
      payment_http.rs, and the _net.pyi stub
    • Cross-lang vectors: net/crates/net/tests/cross_lang_payments/

What this skill deliberately does not cover

• The base mesh, nRPC, capabilities, MCP bridge, event bus — that's the
  net-event-bus skill. This skill assumes the substrate and only covers the
  money layer on top.
• Refund/dispute semantics — the net.payment.dispute@1 tag is reserved;
  no semantics ship today.
• RFQ / dynamic pricing — waits on x402 v2 dynamic-pricing maturity; no
  parallel dynamic flow, no counter-offer object (that absence is the rule).
• Accounts / postpaid / prepaid — bilateral, provider-scoped, and not
  shipped; company-held credits only via licensed partners.
• Inbound HTTP 402 serving — deferred, demand-driven.

If the user asks about these, say where they stand rather than inventing an
API.

Further reading

• Payments documentation