Read our books, programmatically
Every number on this site is available as JSON. The transparency endpoints are read-only by design — no API key, no rate-limit tier, CORS open to any origin. Partner order actions below require a scoped API key; public transparency feeds never move funds.
The cash-out API is a separate, authenticated set of endpoints for partner wallets. It requires an API key created by a registered member and scopes every order to the key that created it.
Transparency
/api/public/reservesLatest signed attestation: reserves, adjusted TSD liability, collateralization, cold/hot split and breakdowns. Values reflect the observation time in asOf, not a new scan. Returns 503 before the first attestation exists.
Try it/api/public/reserves/history?range=24h | 7d | 30d | 90d | allThe append-only signed series behind the charts on /reserves. Each point carries its payload hash and signature so you can prove a historical value was never edited.
Try it/api/public/supplyAggregator-shaped supply data from the same saved attestation as /reserves: symbol, chain, property id, adjusted TSD liability, reserves and collateralization. asOf is the observation time; pending grants/burns can make adjusted liability differ from live confirmed chain supply.
Try it/api/public/statusSame health rules as /status: active checker schedules, issues, TSD's enforced limits and default fees, live redemption capacity and queue depth. Paused jobs carry active:false and health:Paused. Peg numbers carry their attestation time separately.
Try itDeep links (pre-filled swap)
Send visitors straight into a half-finished swap. Open the home page with query settings and the swap box is pre-filled and scrolled into view — the visitor only adds their receiving address and confirms. No key required; it's just a URL.
https://tsd.honest.money/?chain=base&token=USDT&amount=250&ref=yoursite#swap| Setting | Values | Notes |
|---|---|---|
| chain | ethereum | base | Unknown values (including retired networks) fall back to Ethereum. |
| token | USDC | USDT | PYUSD | DAI | Must be a token the chosen chain supports; otherwise the chain's default is used. |
| amount | positive number | Ignored when missing, not a number, or ≤ 0. Min/max limits still apply in the box. |
| ref | any string | Optional. Kept so we can tell which partner site sent the visitor. |
| #swap | fragment | Scrolls the page down to the swap box on load. |
Embed the swap box
Put the working swap box on your own page. It runs inside an iframe: visitors pick a coin, type an amount, add their address and confirm without leaving your site. No key and no sign-in needed — it is the same box that sits on our home page, with the navigation stripped off.
<iframe
src="https://tsd.honest.money/embed?chain=base&token=USDT&amount=250&ref=yoursite"
title="Texas Stable Dollar swap"
width="100%"
height="920"
style="max-width:480px;border:0;border-radius:24px"
loading="lazy"
referrerpolicy="no-referrer-when-downgrade"
></iframe>- •The same settings as the deep link above work here:
chain,token,amountandref. Drop them all for an empty box. - •Give the frame about 920 px of height (the redemption side is taller) and at least 340 px of width. It is a single dark card, so it sits well on either a light or a dark page.
- •After a visitor confirms, the order page — the deposit address, QR code and live status — opens inside the same frame, so the whole swap stays on your site.
- •If your site sets a Content-Security-Policy, allow the frame with
frame-src https://tsd.honest.money. - •Sign-in does not run inside a frame, so the embedded box charges the standard fee. Members who want their discount go to the full site — the box points them there.
Prefer a plain button? A styled link is one line and never needs a height:
<a href="https://tsd.honest.money/?chain=base&token=USDT&amount=250&ref=yoursite#swap"
style="display:inline-block;padding:12px 22px;border-radius:12px;font-weight:600;text-decoration:none">
Swap to TSD
</a>Partner cash-out
Use this to let your users convert TSD back to USDC without leaving your app. Get a key from the account page and send it as the x-api-key header (or Authorization: Bearer). /orders accepts a chain of ethereum, base, or bsc.
One-time or saved address?
A member has one saved USDC cash-out address. Pick the call by what the member asked for:
| Member wants | Call | Send TSD to | Saved address / email |
|---|---|---|---|
| A different address, this cash-out only | POST /cashout/orders with payoutAddress | The depositAddress in that response | Unchanged · no email |
| Their usual saved address | None needed | Their permanent deposit address | Unchanged · no email |
| Every future cash-out to go somewhere new | POST /cashout/payout-address | Permanent deposit address, after they confirm | Changes only after the member confirms by email |
- Never call
/cashout/payout-addressto set a one-time address. It asks the member to change their saved address permanently, and TSD sent to the permanent deposit address still pays the old saved address until they confirm. - TSD sent to the permanent deposit address always pays the saved address as it stands when the TSD arrives. A
payoutAddresssent anywhere else (for example on/cashout/notify) does not change that. - A one-time order's
depositAddressis for that order only. Send exactlyamountbeforeexpiresAt, then pollGET /cashout/orders/:id(or use a status callback) forreleaseTxHash. - Before showing a confirmation screen, echo back the order's
payoutAddressandpayoutAmountso the member can check where the USDC will land.
POST /api/public/v1/cashout/orders
x-api-key: <member's key>
{ "amount": 4000, "payoutAddress": "0x…one-time…", "chain": "ethereum", "source": "HME Wallet" }
201 → { "id": "…", "depositAddress": "T…fresh…", "payoutAddress": "0x…one-time…",
"payoutAmount": …, "expiresAt": "…", … }/api/public/v1/cashout/settingsx-api-keyLive flag, minimum/maximum order sizes, the global redemption fee in basis points, and an `account` block for the member behind your key: their permanent TEXITcoin deposit address, permanent EVM address, saved cash-out address, and their effective (possibly discounted or zero) fee.
/api/public/v1/cashout/deposit-addressx-api-keyThe reusable TEXITcoin deposit address for the member behind your key (safe to cache and display as “your TSD address”), plus their permanent EVM address, saved cash-out address, and effective fee. TSD sent here always pays the saved cash-out address as it stands when the TSD arrives — for a different address on one cash-out, create an order instead (see “One-time or saved address?” above). All fee fields are numbers: redeemFeeBps, defaultRedeemFeeBps, feePercent.
/api/public/v1/cashout/payout-addressx-api-keyThe USDC payout address saved on the member’s account, plus their permanent TEXITcoin deposit address and effective fee. Use this to auto-fill both sides of a cash-out without asking the user to look anything up.
/api/public/v1/cashout/payout-addressx-api-keyChanges where every future cash-out to the member’s permanent deposit address is paid. Only call this when the member has chosen to change their saved address — never for a one-time address. If the account has no saved address yet, it is saved at once and the response has status: "saved". Replacing an existing address returns status: "pending_confirmation": we email the member a confirmation link, nothing changes until they confirm, and payouts keep going to the current address. Show the member “Check your email to confirm” in that case. Requests are rate-limited (429).
{"payoutAddress":"0x…"}/api/public/v1/cashout/couponx-api-keyCheck whether a coupon code is valid and see the fee it would apply. Never consumes a use.
{"code":"EARLYBIRD"}/api/public/v1/cashout/ordersx-api-keyStart a single TSD → USDC redemption on behalf of your user — this is the way to pay a different address for one cash-out. It never changes the member’s saved address and never sends a confirmation email. Each call returns a fresh one-time deposit address that belongs to this order only; send exactly amount TSD to it before expiresAt (24 hours). The response tells you exactly where the user must send TSD: depositAddress (also returned as address, txcDepositAddress and sendTo — same value), with asset: "TSD", network: TEXITcoin Omni property 39, and memo: null (Omni has no memo/tag). Show that address, not the account-level one. payoutAddress is optional — we fall back to the cash-out address on your account, and an explicit payoutAddress always overrides it. Always send refundAddress: the member’s own legacy T… address holding the TSD. If you leave it out, no refund address is recorded and we ask the member if a refund is ever needed; a bridge deposit address (including the member’s permanent one) is refused, because TSD returned there would be cashed out again. The deadline only limits when TSD may be sent: once your transfer is seen it can still finish after expiresAt, and TSD that arrives after the deadline is held for review, not paid automatically — so create the order right before sending and make a new one if less than an hour remains. The member’s negotiated fee is applied automatically (a coupon can only lower it).
{"amount":100,"payoutAddress":"0x…","refundAddress":"TXC…","chain":"ethereum","couponCode":"EARLYBIRD","source":"HME Wallet"}/api/public/v1/cashout/ordersx-api-keyRead-only list of every order on the member account that owns your key, newest first: buys (kind: "mint"), one-time cash-outs (kind: "cashout") and cash-outs sent to the permanent deposit address (kind: "inbox_cashout") — including orders made on the website or with an older key, so a wallet on a new device can rebuild its history. Never returns another account’s orders and never changes anything. Query: limit (1–100, default 50), kind (optional filter), before (ISO time, optional) and cursor (pass nextCursor from the previous page; null means no more). Each order has id, reference (TX-…), kind, status (same names as polling), createdAt, asset, amount, amountExpected and amountReceived as exact decimal strings, depositAddress, depositTxid and createdByThisKey; cash-outs add payoutAddress, payoutTxid, payoutUsdc and payoutChain; buys add recipient, sourceChain, sourceToken, mintTxid and nativeCoin (LTC/DOGE conversions). Fields that don’t apply, or aren’t known yet, are null. For display and reconciliation only — never use it to decide where to send money.
/api/public/v1/cashout/orders/:idx-api-keyRead the current status, the deposit address to send TSD to (depositAddress / address / sendTo), amount received, payout amount, and settlement txids. Mint orders also return direction: "mint", recipient, depositToken, depositTokenContract (the token that actually arrived, once seen) and mintTxid; on mint orders ignore the cash-out-only fields network, addressFormat, feeBps, payoutAmount and payoutAddress. Reading an order never sends its payout: once the TSD is confirmed, our scheduled checker sends the USDC within about a minute, so a short timeout or a dropped connection on your side cannot interrupt a payment. Only the API key that created the order can read it.
Dollar tokens (TSD, CAN)
The same engine issues more than one 1:1 USD-backed token on TEXITcoin. TSD fronts tsd.honest.money; CAN fronts CannabisCoins.com. They share these vaults, this relayer and one proof-of-reserves feed — only the ticker, limits and fees differ. Send your key as x-api-key and name the token with asset. Payouts are always USDC; the TEXITcoin leg always uses a legacy T… address.
/api/public/v1/stables/assetspublicTSD and CAN with property id, accepted stablecoins, enforced global/asset min/max intersection, actual default fees and availability. Minting currently has no fee deduction. Member/coupon redemption fees may differ. depositTokenContracts lists the exact contract of every accepted stablecoin per network (Ethereum and Base), so wallets can pin them and refuse anything else. supplySource:live-chain identifies confirmed chain supply; asOf timestamps the response, so supply can differ from adjusted attestation liability while settlement is pending. No key required.
/api/public/v1/stables/ordersx-api-keyOne shape for every token. direction 'mint' takes stablecoins on Ethereum or Base and grants tokens to a legacy T… address; the response carries a fresh deposit address. direction 'redeem' pays USDC to payoutAddress using the global/member/coupon fee resolution. Mint replies include depositTokenContract (the exact contract to pay). Pay right after creating the order, in one transfer of one token; payments under 1 dollar per transfer are ignored. Tokens are created for the amount that actually arrives, even if it differs from the order. A payment already on-chain before the deadline is processed even if we notice it later, but a payment sent after the order expires is not processed automatically and needs manual review, so never pay within an hour of expiresAt. Poll the order with the cash-out order endpoint.
{
"asset": "CAN",
"direction": "mint",
"chain": "base",
"token": "USDC",
"recipient": "T…",
"amount": 250
}/api/public/v1/stables/native-orderspublic; optional x-api-key tags the order to a partner accountPublic one-off native orders are disabled (403). LTC/DOGE is currently a private account beta using dedicated addresses, not this endpoint.
{
"coin": "LTC",
"amount": 2,
"recipient": "T…",
"refundAddress": "ltc1…"
}Reading a buy (mint) order
Buy orders are read with the cash-out order endpoint (GET /cashout/orders/:id), so the status names are cash-out shaped. For a buy, read them this way:
| status | What it means for a buy |
|---|---|
awaiting_deposit | No payment seen yet. |
detected | The payment is seen on chain and is waiting for confirmations. |
paying | The tokens are being created. |
released | The tokens are minted to recipient (see mintTxid). This is not a USDC payout — a buy order never pays USDC out. |
expired | The deadline passed with no payment found. |
failed | Something went wrong. Contact us with the order id. |
- Confirmations before minting: Ethereum needs 15 blocks and Base needs 30 blocks. A buy of 10,000 dollars or more waits for 60 blocks on either network. Show “waiting for confirmations” while the order is
detected— that wait is normal, not a stall. - Minimum buy: currently 10 dollars. Always read the live limit from
GET /stables/assetsbefore creating an order, because limits can change.
Wrapping desk (majors)
Wrap Bitcoin, Litecoin and Ethereum into Omni tokens on TEXITcoin (wBTC, wLTC, wETH) and unwrap them back to the native coin. Same auth model as cash-out: send your key as x-api-key. Each wrap order gets its own freshly derived deposit address on the base chain; unwrap orders return the wrapped token to the issuer's legacy TEXITcoin address. The wrapped leg is custodial — reserves are held by the issuer and published on /reserves.
/api/public/v1/wrap/assetspublicRegistry of every major we wrap: base and wrapped symbol, network, Omni property id, required confirmations, min/max order size, wrap and unwrap fees in bps, whether the desk is live, plus live reserves, wrapped supply and collateralization. No key required — poll this to build your UI and to disable submit when a desk is paused.
/api/public/v1/wrap/ordersx-api-keydirection is 'wrap' (native in, wrapped out) or 'unwrap' (wrapped in, native out). For a wrap, payoutAddress is the customer's legacy T… TEXITcoin address and the response carries the per-order deposit address on the base chain. For an unwrap, payoutAddress is their BTC/LTC/ETH address and the response tells you where to send the wrapped token. refundAddress and reference are optional; reference is echoed back on every poll.
{
"direction": "wrap",
"asset": "BTC",
"amount": 0.01,
"payoutAddress": "T…", // legacy TEXITcoin address
"refundAddress": "bc1…", // optional
"reference": "seeds:order:123" // optional, echoed back
}/api/public/v1/wrap/orders/:idx-api-keyCurrent status, deposit address (depositAddress / sendTo), amounts, confirmations vs required, fee, and every txid (deposit, mint, burn, payout). Accepts the uuid or the TX-XXXXXXXX short reference. Polling also nudges the order forward, so state is fresh. Only the key that created the order can read it.
Wallet linking & rewards
Lets a partner wallet (Beekeeper, CryptoPOP, HME Wallet) bind itself to a TSD member account by scanning a QR. The wallet shares its TEXITcoin account extended public key only — it is watch-only, so we can read TSD balances and never move funds. We derive addresses across both branches with a gap limit of 20, sample the total TSD balance every hour, and expose a 30-day rolling average for level-up rewards. Linking also fills in the member's TSD and USDC payout addresses so they never type one again.
/api/public/v1/wallet-link?token=…public (single-use token)The QR a member shows in their TSD Swap account encodes this URL. Fetch it with Accept: application/json to get the manifest, or render the page and read the <script type="hm-link-xpubs"> block. It tells you what to sign, which chains we want, who is asking, when the challenge expires, and whether re-binding a new wallet is allowed. Tokens are single-use and live 5 minutes.
/api/public/v1/wallet-linksignatureSend the manifest payload back with a BIP-137 signature over canonicalJson(payload) — keys sorted recursively, no whitespace, UTF-8 bytes, TEXITcoin magic prefix, base64 — signed by m/44'/696969'/0'/0/0. xpubs.TXC is required and must be the account-level extended public key (watch-only); xpubs.EVM is required (plain 0x address or an EVM xpub, where m/0/0 is taken) and becomes the member's automatic USDC redemption payout address; xpubs.BASE is optional and defaults to EVM. We verify the signature, store the xpub, auto-fill the member's TSD and USDC payout addresses, start watching every derived address for TSD, and return a freshly minted partner API key in api_key (scopes cashout + rewards) — so a single scan both links the wallet and authorises the app, replacing any pasted key. The key is shown once; rescanning issues a new one and revokes the previous one. 401 invalid signature, 409 wallet already linked to another account, 403 unknown_signer when re-binding without consent, 410 token used or expired.
{
"payload": {
"v": 1,
"type": "hm-link-xpubs",
"challenge_id": "<from manifest>",
"from": "tsd.honest.money",
"callback_url": "https://tsd.honest.money/api/public/v1/wallet-link?token=…",
"chains": ["TXC", "EVM", "BASE"],
"xpubs": {
"TXC": "xpub…", // required — account xpub, watch-only
"EVM": "0x…", // required — default EVM wallet (or an xpub)
"BASE": "0x…" // optional — defaults to EVM
},
"wallet": "HME Wallet",
"exp": 1767225600,
"issued_at": "2026-09-04T09:32:01.234Z"
},
"signature": "<base64 BIP-137>",
"address": "T…" // signing address, legacy base58
}/api/public/v1/rewards/balance?address=…&days=30x-api-key (rewards)For mineHME level-up rewards. address can be any address we can tie back to a member: their signing address, any address derived from their linked xpub, their permanent TSD Swap inbox, or their linked ETH/Base address. Returns currentBalance, averageDailyBalance over the window, sample count, and which field matched. Balances are Omni TSD (property 39) sampled hourly, so the average can't be gamed by topping up once a day. Requires a key with the 'rewards' scope. Never returns an email or any other personal data.
TEXITcoin address format (legacy only)
TSD is an Omni Layer property on the TEXITcoin blockchain. Omni reference outputs only recognise legacy base58check addresses — the ones that start with a capital T. A bech32 txc1… address will be silently ignored by Omni and the tokens will never arrive, so every endpoint that accepts a TEXITcoin address rejects bech32 before it ever touches the chain.
- Starts with a capital
T, 26–35 characters, base58 (no0,O,Iorl). - Version byte
0x42(P2PKH) or0x32(P2SH) — both are accepted. - Full base58check checksum is verified, so a single mistyped character is rejected.
txc1…bech32 is rejected with a message pointing the user to the legacyT…address in their wallet (Receive → Tokens tab).- No memo, tag or destination tag is required — Omni property 39 has no such field. Any address you send us
refundAddressfor must be a valid legacy address that the member controls — never a bridge deposit address.
The same validation runs on every path: the API, the member dashboard, and the admin console share one checkTxcAddress routine. If an address passes there, it passes everywhere.
Status callbacks (skip the polling)
Each API key can carry an https callback URL, set on your account page under API keys. Every milestone of an order created with that key — deposit seen, deposit confirmed, burn, payout sent, and any failure — is POSTed to that URL as JSON:
{
"type": "payout_sent",
"message": "Sent 99 USDC on ethereum",
"amount": 99,
"chain": "ethereum",
"txid": "0x…",
"occurredAt": "2026-08-06T11:00:00.000Z",
"order": { "id": "…", "status": "released", "payoutAmount": 99, … }
}x-tsd-timestampholds unix seconds;x-tsd-eventrepeats the event type.x-tsd-signatureissha256=followed by the hex HMAC-SHA256 oftimestamp + "." + rawBody, keyed with the signing secret shown next to your key. Compare it with a timing-safe compare and reject timestamps older than a few minutes.- Respond
2xxquickly. Deliveries are best-effort and not retried, so treat them as a fast path and keep the poll endpoint as your source of truth for reconciliation.
Inbound partner webhooks
Partners can push status events back to us so a missed deposit or a payout confirmation is never silent. Each partner has its own shared secret, compared in constant time; if the secret is unset the endpoint returns 503 rather than opening up. Nothing here moves funds — it records an auditable order_events row and pages operations, so a compromised caller cannot spend money.
POST /api/public/v1/webhooks/tsdswap— HME Wallet / Seeds, guarded by theTSDSWAP_API_KEYsecret.POST /api/public/v1/webhooks/cannabis— CannabisCoins.com, guarded by theCAN_WEBHOOKsecret.
Send the secret as Authorization: Bearer or x-api-key. The body is { event, order_id?, message?, amount?, chain?, txid?, data? } — order_id may be a short TX-XXXXXXXX or a full UUID. We respond { ok: true, recorded: true|false, order?: "TX-…" } and page ops in the same beat.
Cash-out deposit heads-up (HME Wallet)
POST /api/public/v1/cashout/notify lets the HME Wallet tell us the moment a member broadcasts a cash-out deposit, so the order can be opened before the first confirmation. The notice is only a hint — the on-chain watcher still confirms the deposit before anything pays out.
x-api-key— the member's own TSD Swap API key (identifies the account;cashoutscope required).x-hme-timestamp— unix seconds; rejected if more than 5 minutes old.x-hme-signature— hex HMAC-SHA256 of${timestamp}.${rawBody}using the sharedHME_ECOSYSTEMsecret.- Body:
{ txid, amount, depositAddress, payoutAddress?, source? }—depositAddressmust be the account's permanent deposit address.payoutAddressis stored as a note only; we never pay to it. That deposit pays the member's saved address. For a one-time address, create an order instead (see “One-time or saved address?”). - Returns
200 { ok: true }; notices are txid-unique, so repeat calls are safe. Errors:401bad signature/key,400bad body.
Verifying an attestation
Each attestation is canonicalized before it is hashed, so anyone can recompute the hash from the published fields. The rule is fixed and public:
- Object keys are sorted alphabetically at every level.
- All numbers are rounded to 6 decimal places; non-finite values become null.
payload_hash = sha256(json), hex encoded.signature = hmac_sha256(secret, payload_hash)— the key is held by the issuer, so the signature proves the row was written by us and never edited afterwards.
Attestations are append-only: rows are never updated or deleted. Recompute the hash for any historical point and compare it with the published payload_hash. If they differ, the number changed and we are caught.
Cadence commitment
We commit to recording a reserve attestation at least once per hour, continuously. The current cadence and the timestamp of the last attestation are both published on /status. A gap in the series is itself evidence — we would rather you see a gap than a fabricated number.
Fair use
Responses are cached for 15–120 seconds. Please poll no more than once per minute; the underlying data does not change faster than that. If you are building something that needs more, get in touch and we will work out a push feed.