SDK Reference#
Onchain OS Payment provides four SDKs — Node.js / Rust / Go / Java — covering middleware mounting, configuration management, and on-chain settlement reconciliation for HTTP Seller scenarios.
For Agent Seller scenarios, use OnchainOS Skill; no SDK required.
Payment-method coverage#
| Payment method | Node.js | Rust | Go | Java |
|---|---|---|---|---|
One-time payment · exact | ✅ | ✅ | ✅ | ✅ |
One-time payment · charge (revenue splits) | Coming soon | Coming soon | Coming soon | Coming soon |
Batch payment · aggr_deferred | ✅ | ✅ | ✅ | ✅ |
Pay-as-you-go · session | Coming soon | Coming soon | Coming soon | Coming soon |
Escrow payment is Agent-Seller only; use OnchainOS Skill; SDKs don't cover it.
Pick your SDK#
Capabilities shared across the four SDKs#
Whichever language you pick, the SDK covers the following capabilities — only the API style differs slightly.
| Capability | Description |
|---|---|
| Route middleware | Mount on an HTTP route to handle 402 / Verify / Settle automatically |
| Multi-scheme declaration | A single route can declare both exact and aggr_deferred (other schemes coming soon) |
| Broker client | Actively call the Broker API (create order, query status, reconcile) |
| State polling / event listening | Listen for payment-completed, aggregated-settle, and other events |
| Error codes and retries | Standardized error codes + recommended retry strategies |
Choosing tips#
My service uses Node.js / Express — how do I start?#
Use the Node.js SDK directly: npm install @okx/onchainos-payment.
High-concurrency, low-latency requirements — which one?#
The Rust SDK has the best performance. The Go SDK strikes a great balance between ergonomics and performance.
My web framework isn't in the supported list — what now?#
All four SDKs expose low-level verify / settle functions that let you manually integrate any framework. See the "manual integration" section of each language's SDK doc.
Don't plan to use the SDK?#
The payment protocol is fully open. You can also call the Broker REST API directly per the API Reference and handle 402 response construction, signature verification, and Settle submission yourself.
But that means you'll need to handle:
- HTTP 402 response spec (Challenge field structure)
- Multi-scheme declaration + Buyer wallet capability detection
- KYT error handling
- Channel state reconciliation (when using
session) - Aggregated-settle event listening (when using
aggr_deferred)
The SDK encapsulates all of the above. Unless you have strong custom needs, or need a payment method the SDK doesn't yet cover (Pay-as-you-go / charge-with-splits), prefer the SDK.