Send, swap and bridge USDT, USDC, BTC, ETH and the rest of the wallet's catalogue from Java — no browser, no wallet extension, and no seed phrase anywhere in your environment. It is built for the services that pay people out: marketplaces, exchanges, payroll and treasury jobs.
Your process holds one half of the signing key; the Paymos server holds the other. Neither side alone can move funds — every swap and withdrawal is co-signed, and your half never reaches the server.
- Non-custodial — a leaked API key can't sign; your co-signing share stays in your process.
- Fee-transparent — every quote is a dry preview with a full
platform / network / routefee breakdown you see before signing anything. - Human amounts, no floats — you pass decimal strings like
"100"/"0.5"; responses come back as raw integer strings. - Java 11+, two dependencies (JNA for the core bridge, Gson for the wire).
The SDK talks in plain asset terms (USDC@base, ETH@arb) and hides the routing and the
2-of-2 signing behind a small, safe surface.
<dependency>
<groupId>io.paymos</groupId>
<artifactId>wallet</artifactId>
<version>1.0.0</version>
</dependency>The native co-signing core is not inside the jar. On first use the SDK downloads the
pinned, platform-matching build from the paymos-wallet-core releases, verifies its SHA-256 against
the release's checksum, and caches it per user.
A prebuilt core exists for Linux x86-64, Linux arm64 and Windows x64. The SDK also
recognises macOS on both architectures, but no macOS build is published yet — there is no Mac to
produce one on, and cross-compiling an Apple dylib elsewhere is not the same thing. On any platform
without a prebuilt core, build the crate yourself and set PAYMOS_NATIVE_LIB — or the
paymos.nativeLib JVM property — to the resulting libwallet_mpc.so / .dylib /
wallet_mpc.dll. The same variable skips the download when you want
it skipped: an offline host, or a corporate proxy that will not reach GitHub.
The SDK controls a Paymos vault, which you own from the Paymos wallet — a Telegram-only Mini App. Open @Ox0000000000000000000Bot, tap Open Wallet, then Settings → Vault API and mint a key:
| Key | Can do | Carries |
|---|---|---|
| read | assets, balances, quoteSwap, quoteWithdraw, movement, movements |
API key only |
| full | everything a read key does, plus swap and withdraw |
API key + your co-signing share |
The key is a vs_live_… string. A full key's co-signing share is decrypted on your device and
never leaves your process. Treat a full secret like a private key.
export PAYMOS_VAULT_SECRET="vs_live_…"
# optional — defaults to https://wallet.paymos.io
# export PAYMOS_BASE_URL="https://wallet.paymos.io"import io.paymos.wallet.Wallet;
import io.paymos.wallet.Types;
public class Main {
public static void main(String[] args) {
Wallet w = Wallet.fromEnv(); // reads PAYMOS_VAULT_SECRET
// Balances: per-asset, raw amount strings + a nullable USD value.
for (Types.Balance b : w.balances())
System.out.println(b.asset + " " + b.amountRaw + " " + b.usd);
// Preview a withdraw — a dry, money-safe quote. Headline is the fee breakdown.
Types.Quote q = w.quoteWithdraw("USDC@base", "25", "0xRecipient…", "exact_out");
System.out.println(q.fees.platform + " " + q.fees.network + " " + q.fees.total);
// Move money (full key only). Amounts are human decimal strings.
Types.Movement mv = w.swap("USDC@base", "ETH@arb", "100", 50, null, null, null);
Types.Movement settled = w.wait(mv.id, null, null);
System.out.println(settled.status);
}
}Amounts: human in, raw out. You pass human decimal strings; the server owns each asset's
decimals and scales them to raw. Responses come back as raw integer strings. Never a float, in
either direction. Amounts.parseUnits / Amounts.formatUnits convert between the two.
Moving money. swap and withdraw (full key only) create a real movement and drive the
2-of-2 co-sign. Before any signature the SDK re-checks that the server's quote echoes exactly
the assets and amount you approved — a decimals bug, contract drift, or a lying server throws
and signs nothing.
Safety caps. minReceive floors the guaranteed receive (PaymosException.SlippageExceeded
below it, nothing signed); maxDebit ceilings the total vault debit — strongly recommended for
unattended exact_out payouts; idempotencyKey makes a retry after an ambiguous failure replay
the same movement instead of paying twice.
Withdraw modes. "exact_out" (default) — the recipient gets exactly amount, the debit is
server-computed. "total_in" — amount is the total debited; the recipient gets it minus fees.
Waiting. wait(id, timeout, interval) polls to a terminal status — completed | failed | refunded | expired | cancelled; nulls mean sensible defaults.
Every call throws a subclass of PaymosException, which carries getMessage() and status()
(the HTTP status, or null for a transport-level failure). Branch on the type:
| Exception | When |
|---|---|
PaymosException.Auth |
401 — API key missing, malformed, or unrecognized |
PaymosException.Forbidden |
403 — the key is valid but lacks the scope this call needs |
PaymosException.InsufficientFunds |
400 — the vault balance can't cover the amount (plus fees) |
PaymosException.QuoteExpired |
400 — the referenced quote expired; fetch a fresh one |
PaymosException.SlippageExceeded |
400 or local — delivered / guaranteed amount fell below your floor |
PaymosException.CrossAssetWithdrawNotAllowed |
400 — a withdraw changed the asset (that's a swap) |
PaymosException.RouteUnavailable |
400 — no route could be quoted right now; retry shortly |
PaymosException.RateLimited |
429 — carries retryAfter() (seconds, or null) |
PaymosException.Conflict |
409 — idempotency key reused with a different request |
PaymosException |
base — 404, any other 4xx/5xx, local refusals, transport errors |
Calling swap / withdraw with a read-only key throws before any movement is created — a
read key can never sign.
- A leaked API key alone cannot move funds — no share, no signature (and the key can be revoked).
- A leaked share alone cannot move funds — no server co-sign.
- Both are required, on purpose. The SDK additionally verifies every message it co-signs, and that the server's quote matches exactly what you approved — so a compromised server can't redirect funds or inflate an amount past your caps.
Treat a full vs_live_… secret like a private key, and back up the share — losing it means
losing your ability to co-sign.
MIT for this wrapper — see LICENSE. The co-signing core it downloads is proprietary; its
binary distribution grants no rights to its source.
Install the SDK, point it at your vault, and ask for a withdrawal with the asset written the way the
wallet writes it — USDT@tron. The same call sends USDT on BNB Chain (USDT@bsc), Ethereum
(USDT@eth), Polygon, Solana, Arbitrum, Avalanche or TON: the asset string is the only difference.
io.paymos:wallet (Maven Central)
Nobody alone. The vault is 2-of-2: your process holds one signing share, the server holds the other, and a transfer needs both. A stolen API key cannot sign, and the server cannot sign without you. Your share never leaves your process.
A quote is a dry run. It prices the route, separates platform, network and route fees, and reserves nothing — ask for as many as you like. A transfer is the same numbers, signed. Nothing moves until your half of the signature exists.
No, and this is the part worth reading twice. The server discloses the exact message it wants signed; the SDK recomputes the digest itself and refuses unless that message belongs to your vault, moves no more than the debit you approved, and matches the request you made. A server asking for anything else gets a refusal, not a signature.
USDT moves on nine chains — Tron, Ethereum, BNB Chain, Polygon, Solana, Arbitrum, Optimism, Avalanche and TON — and USDC on eight: that same list without Tron and TON, with Base instead. Add the native coin of each of those chains, and BTC, LTC, DOGE, XRP, BCH, DASH, ZEC and ADA, and the catalogue is 21 assets across 18 chains. It is also the authority: an asset it does not list cannot be quoted or sent, in any SDK.
Every quote breaks the cost into platform, network and route, and amounts come back as raw integer
strings rather than floats: money that has been through a float is money with a rounding error in
it. You pass human amounts in ("100", "0.5") and read exact integers back.
That is what it is for: headless, no browser, no wallet extension, no seed phrase in the environment. A worker holding one share can pay out continuously, and losing that machine costs the ability to sign — not the funds.
Every money-moving call takes an idempotency key. Repeating a call with the same key returns the original operation instead of starting a second one, so a retry after a timeout cannot pay twice.
Every SDK here speaks to the same vault API and enforces the same rules; pick the one your service is written in. The signing core is shared, so a fix there reaches all of them.
| Language | Package | Repository |
|---|---|---|
| Python | pip install paymos-wallet |
python-wallet-sdk |
| TypeScript / Node.js | npm install @paymos/wallet |
typescript-wallet-sdk |
| Go | go get github.com/paymos-labs/go-wallet-sdk |
go-wallet-sdk |
| Rust | cargo add paymos-wallet |
rust-wallet-sdk |
| C# / .NET | dotnet add package Paymos.Wallet |
csharp-wallet-sdk |
| Java (this one) | io.paymos:wallet |
java-wallet-sdk |
| Ruby | gem install paymos-wallet |
ruby-wallet-sdk |
| PHP | composer require paymos/wallet |
php-wallet-sdk |
| Signing core | paymos-wallet-core |
paymos-wallet-core |
- wallet.paymos.io — the product, the supported networks, and guides for the routes people ask about most: USDT BEP20 to TRC20, USDC between chains, and the rest.
- Networks and assets — every chain and token the wallet carries, with the standard each one is named by.
- USDT BEP20 → TRC20 — a worked route, priced live; the other pairs are linked from it.