On this page

BALBOA market-maker API

The market-maker API lets an approved market maker's systems work with its BALBOA settlement account directly: read the account and its limits, the settlement wallet's BALBOA1 balance, its transactions, and where money may go in and out — and mint and redeem BALBOA1: make deposit-backed mint orders, and redeem BALBOA1 for USDT to its own registered addresses.

It is not the customer portal's API. It has its own credentials — an Ed25519 key pair per key, of which BALBOA only ever holds the public half — its own limits, its own log, and no sessions or cookies of any kind.

Nothing here can mint BALBOA1 on its own say-so. A mint order says what you will send; BALBOA1 is minted only once your USDT arrives at BALBOA's Treasury from one of your registered source addresses — and an order made through the API takes a transfer only for its exact amount. A redemption pays only to one of your registered destinations, which only your operations contact adds, in the portal. A key that leaked can make orders, and redeem to your own addresses, within its limits — and no more.

Start in the sandbox. It is a deployment of its own, on the Sepolia test network, with test keys (bk_test_…) and test money: integrate there, mint and redeem as much as you like, and move to production — live keys (bk_live_…), where a key with the mint or redeem scope moves real money — when it works. The code does not change, only the base URL and the key (The sandbox). The test vectors below let you get signing right before your first call.

Try it in Postman

Every endpoint, each request signed for you with your own key. Set keyId and privateKey, then send Server time. How

Postman collection

Support and emergencies

Write to [email protected] — quote the request_id of any call you ask about, and your key id. BALBOA finds a call by its request id, answered or refused.

If you think a private key has leaked, stop it yourself first: your operations contact can suspend any of your keys at once from the portal (Settlement account → API keys → Suspend this key). Every request with it is refused from that moment. Then write to support: we revoke it and issue a new key from a new key pair. A key you suspended is restored only when you ask and two BALBOA admins agree.

Hosts

The API is at https://<API host>/api/mm/v1/…. BALBOA tells you the host: a dedicated API host, or the application's own host while that is being set up. The paths are the same on both. The examples here write it as BASE_URL: set it from your configuration, never hard-code it — the sandbox's is another, https://api-sandbox.<domain>, beside production's https://api.<domain>.

Once the dedicated host is live, the application's host stops serving the API and answers 421 with code: "wrong_host" and the host to use in host. Always use https://: a request sent over plain HTTP has already travelled in the clear before any redirect.

The sandbox

A separate deployment for integrating and testing: the same API, the same code, on the Sepolia test network (chain id 11155111), with test keys and test money. Nothing in it is real, and nothing crosses between it and production — not a key, an account or a record: keys, source addresses and destinations are registered in each.

SandboxProduction
API (BASE_URL)https://api-sandbox.<domain>https://api.<domain>
Portal, for your operations contacthttps://sandbox.<domain>/portalhttps://app.<domain>/portal
Keysbk_test_… onlybk_live_… only
ChainSepolia (11155111), and Solana devnet where it is offeredEthereum (1), and Solana mainnet where it is offered
USDTa test token: six decimals, minted by anyone; on Solana devnet, Circle's devnet USDCTether

BALBOA gives you the exact hosts. A key of the other environment is refused before it is looked up — 401 with reason: "wrong_environment". Every page of the sandbox's portal carries a banner saying it is the sandbox, and every email it sends starts [Sandbox].

Getting in. Do not register on the portal: the sandbox checks no identities, so a login made there would wait at verification with nowhere to go. BALBOA creates your sandbox login and your settlement account, and registers your source address, your wallets and a test key, in one step. Send your BALBOA contact:

  • your operations contact's email — the sandbox login is made for it;

  • a source address — an Ethereum address you control, that your test USDT will come from;

  • your settlement wallet — where BALBOA1 is minted to you, and what a redemption burns from. It may be the same address as the source;

  • your desk wallets, if you want more than one wallet to mint to and redeem from (Desk wallets) — a label and an address for each. They are ready when the account is, with your limits shared between them;

  • where your USDT is redeemed to — the addresses, if you want others than your settlement wallet. Each can be used about an hour after it is registered;

  • your public key — see Getting a key, step 1 — and, if you want the allowlist tested, the addresses you will call from;

  • to test on Solana too, a Solana source address and a Solana settlement wallet (it may be the same).

BALBOA sets all of it up together, and issues a test key with read, mint and redeem and its limits. You are emailed the key's id and a link to choose your operations contact's password — it works for seven days, and Forgot password? on the sandbox's sign-in page gives you a new one. The key works at once, with the private half you kept.

Getting a test key is the same as a live one: generate an Ed25519 key pair, send the public key. A test key works as soon as it is issued — one BALBOA admin issues it, where a live key waits for a second — and may name no addresses, in which case any address may use it: so a bad signature from anywhere is never counted against it, and one is answered with the string the server signed over (canonical), to compare with yours. Name your addresses anyway if you want the allowlist tested.

Test funds. The sandbox's USDT is a test token — deposit.usdt_contract on GET /settlement — whose mint anyone may call. Mint some to one of your registered source addresses, then send it from that address to deposit.address, exactly as you would real USDT: that is what a mint order waits for. With Foundry's cast, and a wallet you have given it once (cast wallet import sepolia-test --interactive — never a private key on a command line):

# 10,000 test USDT (six decimals) to your source address, from any wallet with a little Sepolia ETH
cast send <usdt_contract> "mint(address,uint256)" <your source address> 10000000000 \
  --rpc-url https://ethereum-sepolia-rpc.publicnode.com --account sepolia-test
# then, for a mint order of that amount, from the source address itself to the Treasury
cast send <usdt_contract> "transfer(address,uint256)" <deposit.address> 10000000000 \
  --rpc-url https://ethereum-sepolia-rpc.publicnode.com --account my-source

Whichever wallet sends pays a little Sepolia ETH for gas: any Sepolia faucet gives some. Your operations contact finds all of this — the commands for your own addresses, a mint with your wallet button and a list of faucets — on the sandbox portal's Test funds page. BALBOA1 in the sandbox is minted, and redemptions paid, by the platform, as in production.

On Solana. Where the sandbox offers Solana — GET /settlement's deposits has an entry with "chain": "solana" — it is on Solana devnet, and USDT there is played by Circle's devnet USDC, that entry's usdt_contract: six decimals, like USDT. Get some from Circle's faucet (https://faucet.circle.com, Solana Devnet) to your registered Solana source address, and a little devnet SOL for the fees from https://faucet.solana.com. Then make a mint order with "chain": "solana", and send that amount from the source address to that entry's address — with the Solana CLI's spl-token, signed by the source address's keypair:

spl-token transfer --url devnet --owner my-source.json <usdt_contract> 250 <address>

It is minted once the transfer is finalized, in your Solana settlement wallet. The Test funds page says the same for your own addresses.

What behaves differently. Everything you code against — signing, the limit stack and its codes, idempotency, statuses and steps — is the same. What is not:

  • Faster confirmations. deposit.confirmations is lower (a couple of blocks, where production waits twelve), and a paid redemption reads completed sooner. Read the figure from /settlement; never hard-code it.

  • A shorter wait for new destinations — an hour or so rather than a day: usable_from on /settlement says when.

  • Lower caps. The limits BALBOA sets you, and the treasury's own daily capacity, may be smaller than production's: a larger mint or redemption may be refused, or wait scheduled for the next UTC day. Your /account shows your limits.

  • A test chain. Sepolia's blocks come about every twelve seconds, and it can stall or reorganise more than Ethereum does. Its tokens are worth nothing, and are nothing on any other chain.

  • Test balances can be changed by people other than you — until BALBOA has moved the sandbox's contracts to a Safe of its own. While its stand-in Safe has no owners, anyone on Sepolia can use it to burn test BALBOA1 from any wallet, move the test USDT sent to the Treasury, or pause minting and redeeming for everyone. Nothing of value is at stake; if a balance changes under you, or everything stops, tell BALBOA.

  • It may be reset. The sandbox's data — accounts, keys, orders — may be wiped, with notice where we can. Keep nothing there you need, and after a reset send a new public key.

From zero to a first mint and redemption

The whole loop, in the order you meet it, with the Node.js sample's call — BALBOA_BASE_URL set to the sandbox's API host, BALBOA_KEY_ID to your test key's id. Amounts under your limits and under the review thresholds go straight through; the waits are the sandbox's, not production's.

  1. Your key. Once BALBOA has sent its key id, check it:

    const me = await call('GET', '/api/mm/v1/account')
    // me.key.key_id: bk_test_…; me.key.scopes: read, mint, redeem; me.limits: your account's and the key's limits
  2. Test funds. Mint test USDT to your source address, and give that address a little Sepolia ETH for gas (see Test funds above, or the portal's Test funds page, which prints the commands for your own addresses):

    cast send <usdt_contract> "mint(address,uint256)" <your source address> 1000000000 \
      --rpc-url https://ethereum-sepolia-rpc.publicnode.com --account sepolia-test   # 1,000 test USDT
  3. A mint order. Ask for what you will send:

    const { mint_order } = await call('POST', '/api/mm/v1/mint-orders',
      { amount: '1000.00', wallet: 'settlement' }, { idempotencyKey: 'sandbox-mint-0001' })
    // status: awaiting_transfer; mint_order.deposit: address, amount, source_addresses, send_by
  4. The deposit. From your source address, send exactly mint_order.deposit.amount to mint_order.deposit.address:

    cast send <usdt_contract> "transfer(address,uint256)" <deposit.address> 1000000000 \
      --rpc-url https://ethereum-sepolia-rpc.publicnode.com --account my-source
  5. Minted. Follow the order until it is minted — confirming once BALBOA's watcher has seen the transfer (it looks every 30 seconds), then issuing, then minted, with the mint's hash in hashes; a minute or two in all:

    const order = await call('GET', `/api/mm/v1/mint-orders/${mint_order.id}`)
    // order.status: minted; GET /api/mm/v1/balances shows the BALBOA1 in your settlement wallet
  6. A destination, past its wait. BALBOA registered one with your account; your operations contact can add others in the portal. A new one is usable an hour after it is added in the sandbox (a day in production):

    const { redemption_destinations } = await call('GET', '/api/mm/v1/settlement')
    // status: cooling until usable_from, then ready
  7. A redemption, to a destination that is ready:

    const { redemption } = await call('POST', '/api/mm/v1/redemptions',
      { amount: '500.00', destination: redemption_destinations[0].id }, { idempotencyKey: 'sandbox-redeem-0001' })
  8. Paid. Follow it through processing (the BALBOA1 is burned from your settlement wallet), sending and sent — the test USDT is at the destination, its hash in hashes.payout — to completed, a few minutes later:

    const r = await call('GET', `/api/mm/v1/redemptions/${redemption.id}`)

Then do the same with your own code, your own amounts and your own idempotency keys — and try what goes wrong: a signature over the wrong string (the sandbox answers with the one it signed over), an amount past a limit, a destination still cooling, a retry under the same Idempotency-Key.

Getting a key

  1. Generate an Ed25519 key pair on the machine that will sign requests, and keep the private key there — in an HSM or secrets manager if you have one. BALBOA never needs it and never asks for it. Any of these works.

    With OpenSSL 3 (openssl version must say OpenSSL 3; macOS's own /usr/bin/openssl is LibreSSL, which answers Algorithm ed25519 not found — use brew install openssl@3):

    openssl genpkey -algorithm ed25519 -out balboa-mm.pem        # private key: keep it
    openssl pkey -in balboa-mm.pem -pubout -out balboa-mm.pub   # public key: send this

    With Node.js 18 or later:

    node -e "const { generateKeyPairSync } = require('node:crypto'); const fs = require('node:fs'); const { privateKey, publicKey } = generateKeyPairSync('ed25519'); fs.writeFileSync('balboa-mm.pem', privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 }); fs.writeFileSync('balboa-mm.pub', publicKey.export({ type: 'spki', format: 'pem' }))"

    With Python and cryptography:

    from cryptography.hazmat.primitives import serialization as s
    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
    
    key = Ed25519PrivateKey.generate()
    open("balboa-mm.pem", "wb").write(key.private_bytes(s.Encoding.PEM, s.PrivateFormat.PKCS8, s.NoEncryption()))
    open("balboa-mm.pub", "wb").write(key.public_key().public_bytes(s.Encoding.PEM, s.PublicFormat.SubjectPublicKeyInfo))
  2. Send BALBOA the public key (the PEM block, or its 32 bytes in base64 or hex — never the private key) and the IP addresses or networks your requests will come from. Your operations contact does it in the portal — Settlement account → API keys → Request a key, in their own signed-in session — and is shown the key's fingerprint at once; or sends it to support. As BALBOA sees them: your egress address, after any NAT or proxy of yours. GET /api/mm/v1/time answers it as your_address — call it from each machine that will sign. A live key must name at least one; the widest accepted is an IPv4 /16 or an IPv6 /32.

    Mind IPv6. A machine with both IPv4 and IPv6 may reach BALBOA over either, and an IPv6 address may change within its network as the host renumbers. Either name your IPv6 network (your /64, or wider up to a /32) as well as your IPv4 address, or make your client use one address family only.

  3. BALBOA issues the key and tells you its key id. A live key works once a second BALBOA admin has approved it: until then it is refused, and nothing it is refused for counts towards suspending it. A test key, in the sandbox, works at once. Check the key's fingerprint before you use it — the portal shows it when you ask for the key and on the key itself, and we read the same one out. This prints it in exactly the form we show it, SHA256: and the base64 SHA-256 of the 32 raw public-key bytes without the trailing =:

    printf 'SHA256:%s\n' "$(openssl pkey -pubin -in balboa-mm.pub -outform DER | tail -c 32 | openssl dgst -sha256 -binary | base64 | tr -d '=')"

    or, without OpenSSL 3:

    node -e "const c = require('node:crypto'); const x = c.createPublicKey(require('node:fs').readFileSync('balboa-mm.pub')).export({ format: 'jwk' }).x; console.log('SHA256:' + c.createHash('sha256').update(Buffer.from(x, 'base64url')).digest('base64').replace(/=+$/, ''))"
  4. Check it works: GET /api/mm/v1/account is the API's "who am I" — it answers with the key you signed with, its scopes, allowlist and expiry, and your account.

Each key has scopes — what it may do: read (everything you GET), mint (make and cancel mint orders) and redeem (make and cancel redemptions). A key that mints or redeems also needs read to follow what it makes — GET /mint-orders/:id, /redemptions/:id and the lists are read's — and BALBOA issues money keys with read unless you ask otherwise. A key holds mint or redeem only with its own limits for it set — the most one order or redemption may be, and the most in a UTC day (see The limit stack) — so a key that leaked is never an unlimited minting key; and only once your account's own daily mint and redeem limits are set, which you meet before any platform-wide cap. Ask BALBOA for the limits your desk needs. Give each system the scopes it needs and no more: a key that only watches balances needs read alone.

Rotation. Generate a new key pair and send the new public key. BALBOA issues a replacement key with the same scopes, allowlist and limits; your operations contact is emailed once a second admin has approved it, with the time the old key stops. The old key keeps working for an overlap (72 hours by default) and then expires. Switch within the overlap — the new key id and its private key together: a key id signed with the other key's private key is a bad signature. An Idempotency-Key is your account's, not a key's: a request the old key sent, retried with the new one under the same Idempotency-Key, answers what it answered — it is never made twice (see Idempotency). The key's own daily limits start from nothing on the new key: each key's day is its own. Watch key.expires_at on GET /api/mm/v1/account: your operations contact is also emailed a week before any key expires, a day before, and when it has. Adding an address to a live key's allowlist, a scope, or raising one of its limits needs two BALBOA admins; removing an address or a scope, or lowering a limit, applies at once.

Revocation is immediate. A public key is used for one key only, ever.

Authentication

Every request except GET /api/mm/v1/time carries four headers:

HeaderValue
BALBOA-KeyThe key id: bk_live_ or bk_test_ and 24 letters and digits.
BALBOA-TimestampUnix time in whole seconds, digits only (1790000000). No fraction, sign, exponent or spaces.
BALBOA-Nonce16 to 64 characters from A–Z a–z 0–9 - _, new for every request.
BALBOA-SignatureThe Ed25519 signature of the string below, in standard base64 (64 bytes; padding optional).

The string you sign

Ten lines joined with \n (a single line feed, no trailing newline); a line with nothing to say is empty, never left out:

v1
{METHOD}
{canonical path}
{canonical query}
{BALBOA-Timestamp}
{BALBOA-Nonce}
{BALBOA-Key}
{Idempotency-Key header as sent, or empty}
{Content-Type header as sent, or empty}
{hex sha256 of the raw body, or of the empty string}
  • {METHOD} — upper case: GET, POST.

  • {canonical path} — the request's path with every empty segment dropped (so a trailing slash, or a doubled one, signs as the path without it), each segment percent-decoded and then encoded again so that only A–Z a–z 0–9 - . _ ~ stay as they are and every other byte of its UTF-8 is %XX with upper-case hex: /api/mm/v1/transactions/payment:7 signs as /api/mm/v1/transactions/payment%3A7. A path never has . or .. segments, nor an encoded / inside one.

  • {canonical query} — the query's parameters as a server reads them (each key and value percent-decoded, + a space; a parameter with no = has the empty value), each key and value encoded as the path's segments are, then sorted by encoded key and then by encoded value, and joined as key=value with &. Empty when there is no query. ?limit=2&kind=deposit,redemption signs as kind=deposit%2Credemption&limit=2. The order you send them in, how you spell them on the wire, and repeated keys all sign the same — so send them as you like, and sign them this way. This is AWS Signature Version 4's canonical query string.

  • {BALBOA-Timestamp}, {BALBOA-Nonce}, {BALBOA-Key} — exactly the header values.

  • {Idempotency-Key …} — the Idempotency-Key header's value exactly as you send it, or an empty line when you send none. The read endpoints do not need one; every POST must send one (see Idempotency).

  • {Content-Type …} — the Content-Type header's value exactly as you send it (application/json), or an empty line when you send none. Set it yourself whenever there is a body: some HTTP clients add one of their own (Node's fetch sends text/plain;charset=UTF-8 for a string body), and a header you did not sign is a bad signature.

  • The last line is the lower-case hex SHA-256 of the exact bytes of the body. With no body, it is the hash of nothing: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. A GET has no body: one sent with a GET is dropped before it arrives, so sign the empty hash.

Paths have no trailing slash. A path with one is answered 308 with the path without it; since the signature is over the canonical path, following it would still verify — but do not rely on it: send the path as documented.

What is checked

In this order — and a failure says which, wherever saying so gives nothing away to someone who does not hold your private key:

CheckTold?
HeadersAll four present and well-formed.Yes: reason names it.
EnvironmentA bk_test_ key is refused by production, a bk_live_ key by a test deployment.Yes: wrong_environment.
TimestampWithin 60 seconds of the server's clock, either way.Yes, with the server's time: timestamp_expired, timestamp_in_future.
Key and signatureThe key id is one of BALBOA's, and the signature verifies with its public key.No. Whether a key id exists, and whether a signature verified, are never said.
AddressThe request comes from an address in the key's allowlist.Yes, once the signature verified: ip_not_allowed, with the address seen as your_address.
Key stateActive: not awaiting approval, suspended, revoked or past its expiry.Yes, once the signature verified: key_pending, key_suspended, key_revoked, key_expired, and key_status.
NonceOnce per key. A request whose nonce the key has used before is a replay.Yes, once the signature verified: replayed_nonce.
BodyAt most 16 KB (16,384 bytes). A larger body is refused (413) before it is read.Yes.

A retry is a new request: sign it again with a new timestamp and a new nonce. Your HTTP client and any proxy of yours must never retry a request on its own — a retried request reuses its nonce, is refused as a replay, and replays count towards suspending your key.

Key ids are not secret. They travel in every request. Someone who learns one cannot sign with it — and cannot get your key suspended either: a bad signature counts against the key only when it comes from an address your key names. From anywhere else it counts against the address that sent it.

When a call is refused: 401 checklist

Work down in the order the server checks. The answer's reason, when there is one, tells you where to start.

  1. *missing_header, `malformed_** — the four headers, spelled as above. Common: a timestamp in milliseconds; a nonce with + or /` (use base64url); a signature in hex or base64url instead of standard base64; a key id with a stray space or newline from a config file.

  2. wrong_environment — a bk_test_ key against production, or a bk_live_ key against the sandbox.

  3. timestamp_expired / timestamp_in_future — server_time in the answer is the server's clock. Sync yours (NTP). Common: a request signed ahead of time and queued; a clock in the wrong time zone treated as UTC.

  4. No reason: the key id or the signature. Check your signing code against the test vectors first — every line of all three must match. Common mistakes:

    • the query signed as sent (unsorted, or , left bare) instead of in its canonical form; a + meant as a plus sign, which is a space unless sent as %2B;

    • a trailing slash, or a path segment not encoded (payment:7 signs as payment%3A7);

    • a Content-Type your HTTP client added, or changed (; charset=utf-8), that you did not sign — or one you signed and did not send;

    • an Idempotency-Key sent and not signed, or signed and not sent;

    • the body re-serialised after it was hashed (spacing, key order, escaping): hash and send the very same bytes;

    • a trailing newline on the string you sign, or \r\n between lines;

    • the key id of one key with the private key of another (after a rotation, switch both together);

    • the method in lower case.

  5. ip_not_allowed — your_address is the address the request came from. If it is yours, ask BALBOA to add it (check IPv6). If it is not, someone else holds your private key: suspend the key and tell us.

  6. key_pending, key_suspended, key_revoked, key_expired — the key's state. A pending key waits for a second BALBOA admin.

  7. replayed_nonce — a new random nonce for every request, retries included, and no automatic retries.

Test vectors

Check your signing code against these before calling the API. They use the example key below, whose private key is published here: never use it for anything else. BALBOA refuses to issue a key with it. The timestamps are fixed, so these exact requests would be refused as stale — that is the point of a vector: your code must produce these exact strings and signatures. (The paths are illustrative: a signature does not depend on the route existing.)

The example key:

{
  "seed_hex": "689e3a307f30533786ac2cf04406275947df54c61b1b5448f34a5e848ebb890b",
  "public_key_base64": "aKMgNB+XBiONYnZCHJw6MkWlO7eI+/3XlqjbucoHuYU=",
  "public_key_hex": "68a320341f9706238d6276421c9c3a3245a53bb788fbfdd796a8dbb9ca07b985",
  "private_key_pem": "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIGieOjB/MFM3hqws8EQGJ1lH31TGGxtUSPNKXoSOu4kL\n-----END PRIVATE KEY-----\n",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaKMgNB+XBiONYnZCHJw6MkWlO7eI+/3XlqjbucoHuYU=\n-----END PUBLIC KEY-----\n",
  "fingerprint": "SHA256:6UZhxqSIZg99ugN5E1qHC86kfzOIsUwpIJdDLMnR/CU",
  "key_id": "bk_test_D0cExampleKeyNotForUse01"
}

Vector 1, a GET with its query unsorted and a comma in a value:

{
  "method": "GET",
  "target": "/api/mm/v1/transactions?limit=2&kind=deposit,redemption",
  "timestamp": "1790000000",
  "nonce": "q7Hc2mZr9TfXw4LpNd8sKe1Y",
  "idempotency_key": "",
  "content_type": "",
  "body": "",
  "body_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "canonical_path": "/api/mm/v1/transactions",
  "canonical_query": "kind=deposit%2Credemption&limit=2",
  "canonical": "v1\nGET\n/api/mm/v1/transactions\nkind=deposit%2Credemption&limit=2\n1790000000\nq7Hc2mZr9TfXw4LpNd8sKe1Y\nbk_test_D0cExampleKeyNotForUse01\n\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "signature": "Du9JBa2N/Rdb0pBY/6pwj3Dcj95OP0418Yd5LujacewCtmYgtWBHN829JvRM6AQB5I6CAtCMd4bNT2pEw7uyCg=="
}

Vector 2, a POST with a JSON body (exactly these 41 bytes), its Content-Type and an Idempotency-Key:

{
  "method": "POST",
  "target": "/api/mm/v1/example",
  "timestamp": "1790000060",
  "nonce": "Zp3_vN8-Lk2QxR7mWd5sTu9H",
  "idempotency_key": "desk-42-order-0007",
  "content_type": "application/json",
  "body": "{\"amount\":\"250.00\",\"reference\":\"desk-42\"}",
  "body_sha256": "114fc525faa14080b9306921c94c9b5144fe1b5fb20c62cfbe0db29b14e8e197",
  "canonical_path": "/api/mm/v1/example",
  "canonical_query": "",
  "canonical": "v1\nPOST\n/api/mm/v1/example\n\n1790000060\nZp3_vN8-Lk2QxR7mWd5sTu9H\nbk_test_D0cExampleKeyNotForUse01\ndesk-42-order-0007\napplication/json\n114fc525faa14080b9306921c94c9b5144fe1b5fb20c62cfbe0db29b14e8e197",
  "signature": "0xF8MSJl/B2XZueV+EwE5rzH1XwYkY96kdFjpVMXTa12URvYMrxKnYsapG65BfdU/+Gg6GNkSt5l1XSdPGYzDw=="
}

Vector 3, the awkward cases together: a : in a path segment and a trailing slash; a repeated key, interleaved; a + that is a space and a %2B that is a plus; a non-ASCII value and a ~; and a parameter with no value:

{
  "method": "GET",
  "target": "/api/mm/v1/transactions/payment:7/?limit=10&kind=payment&cursor=a+b%2Bc&kind=deposit&note=caf%C3%A9~x&flag",
  "timestamp": "1790000120",
  "nonce": "Vx9-kT3_mQ7wLp2RzN8cYd4F",
  "idempotency_key": "",
  "content_type": "",
  "body": "",
  "body_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "canonical_path": "/api/mm/v1/transactions/payment%3A7",
  "canonical_query": "cursor=a%20b%2Bc&flag=&kind=deposit&kind=payment&limit=10&note=caf%C3%A9~x",
  "canonical": "v1\nGET\n/api/mm/v1/transactions/payment%3A7\ncursor=a%20b%2Bc&flag=&kind=deposit&kind=payment&limit=10&note=caf%C3%A9~x\n1790000120\nVx9-kT3_mQ7wLp2RzN8cYd4F\nbk_test_D0cExampleKeyNotForUse01\n\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "signature": "vrWI1GDBDPwe9fgsUfXrtbNkU4iImNRU7HlWED1LlLxPH2giZ8wXZnfHdFT0XPzKtmLLisHQBMdrPKRhbkbFDg=="
}

Vector 4, a real mint order — POST /api/mm/v1/mint-orders — with its body (exactly these 41 bytes), its Content-Type and its Idempotency-Key:

{
  "method": "POST",
  "target": "/api/mm/v1/mint-orders",
  "timestamp": "1790000180",
  "nonce": "Rk4_Tq8-Wm2ZxN7pLd5sVh3C",
  "idempotency_key": "desk-42-mint-0001",
  "content_type": "application/json",
  "body": "{\"amount\":\"250.00\",\"wallet\":\"settlement\"}",
  "body_sha256": "519fa5ed872e7c55f1d560ec39040553de10d57f7178c39bba40a28266dff546",
  "canonical_path": "/api/mm/v1/mint-orders",
  "canonical_query": "",
  "canonical": "v1\nPOST\n/api/mm/v1/mint-orders\n\n1790000180\nRk4_Tq8-Wm2ZxN7pLd5sVh3C\nbk_test_D0cExampleKeyNotForUse01\ndesk-42-mint-0001\napplication/json\n519fa5ed872e7c55f1d560ec39040553de10d57f7178c39bba40a28266dff546",
  "signature": "B/iMPThLTWvwmPkzvY00flq1FrfR4ucxcSgqMWRQIHiVOn9GbR5uXsrRkLUkk/Et8TyCdcgM6GHQ9aDpNgcuCA=="
}

Ed25519 signatures are deterministic: the same key and string always give the same signature, so yours must match byte for byte. In the sandbox, a request whose signature does not verify is answered with the string the server signed over (canonical), to compare with yours; production never does.

Signing in Node.js

Node 18 or later, no dependencies. canonicalPath and canonicalQuery are the two rules above; signedHeaders is everything else.

import { createHash, createPrivateKey, randomBytes, sign } from 'node:crypto'
import { readFileSync } from 'node:fs'

const BASE_URL = process.env.BALBOA_BASE_URL                         // https://<API host>, from BALBOA
const KEY_ID = process.env.BALBOA_KEY_ID                             // bk_live_…
const PRIVATE_KEY = createPrivateKey(readFileSync('balboa-mm.pem'))  // PKCS#8 PEM

/** RFC 3986: only A–Z a–z 0–9 - . _ ~ stay; every other byte is %XX, upper-case. */
const encode = s => encodeURIComponent(s).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)

/** The path as signed: empty segments dropped, each segment decoded and encoded again. */
export const canonicalPath = pathname =>
  `/${pathname.split('/').filter(Boolean).map(s => encode(decodeURIComponent(s))).join('/')}`

/** The query as signed: each parameter decoded and encoded again, sorted by key then value, joined k=v with &. */
export const canonicalQuery = params => [...params]
  .map(([k, v]) => [encode(k), encode(v)])
  .sort(([k1, v1], [k2, v2]) => (k1 < k2 ? -1 : k1 > k2 ? 1 : v1 < v2 ? -1 : v1 > v2 ? 1 : 0))
  .map(([k, v]) => `${k}=${v}`)
  .join('&')

/**
 * The headers for one request to `target` ('/api/mm/v1/transactions?kind=deposit'): the four
 * BALBOA- ones, and the Idempotency-Key and Content-Type they sign. `timestamp` and `nonce` are
 * for the test vectors only.
 */
export function signedHeaders(method, target, body = '', { idempotencyKey = '', contentType = '', timestamp, nonce } = {}) {
  timestamp ??= String(Math.floor(Date.now() / 1000))
  nonce ??= randomBytes(24).toString('base64url') // 32 URL-safe characters
  const url = new URL(target, 'https://example.invalid')
  const message = [
    'v1', method, canonicalPath(url.pathname), canonicalQuery(url.searchParams), timestamp, nonce, KEY_ID,
    idempotencyKey, contentType, createHash('sha256').update(body).digest('hex'),
  ].join('\n')
  return {
    'BALBOA-Key': KEY_ID,
    'BALBOA-Timestamp': timestamp,
    'BALBOA-Nonce': nonce,
    'BALBOA-Signature': sign(null, Buffer.from(message, 'utf8'), PRIVATE_KEY).toString('base64'),
    ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    ...(contentType ? { 'Content-Type': contentType } : {}),
  }
}

/** One call. Never retried here: a retry is a new call, signed afresh. */
export async function call(method, target, body, { idempotencyKey } = {}) {
  const raw = body === undefined ? '' : JSON.stringify(body) // sign exactly the bytes you send
  const res = await fetch(`${BASE_URL}${target}`, {
    method,
    headers: signedHeaders(method, target, raw, { idempotencyKey, contentType: raw ? 'application/json' : '' }),
    body: raw || undefined,
    redirect: 'error', // a signed request is never re-sent somewhere else
  })
  const text = await res.text()
  let answer = null
  try { answer = JSON.parse(text) } catch { /* an edge proxy's 502 or 504 is not JSON */ }
  if (!res.ok || answer === null) {
    const id = answer?.request_id ?? res.headers.get('BALBOA-Request-Id') ?? 'none: it never reached BALBOA'
    throw new Error(`${res.status} ${answer?.reason ?? answer?.code ?? 'not_json'}: ${answer?.error ?? text.slice(0, 200)} (request ${id})`)
  }
  return answer
}

// const { items, next_cursor } = await call('GET', '/api/mm/v1/transactions?kind=deposit&limit=50')
// const { mint_order } = await call('POST', '/api/mm/v1/mint-orders', { amount: '250.00', wallet: 'settlement' }, { idempotencyKey: 'desk-42-mint-0001' })

Signing in Python

Python 3.9.2 or later (earlier ones also split a query on ;), with cryptography and requests. parse_qsl needs keep_blank_values=True, or a parameter with no value is dropped from what you sign and not from what you send.

import base64, hashlib, json, secrets, time
from urllib.parse import parse_qsl, quote, unquote, urlsplit

import requests
from cryptography.hazmat.primitives.serialization import load_pem_private_key

BASE_URL = "https://<API host>"  # from BALBOA
KEY_ID = "bk_live_…"
with open("balboa-mm.pem", "rb") as f:
    PRIVATE_KEY = load_pem_private_key(f.read(), password=None)


def encode(s):
    """RFC 3986: only A-Z a-z 0-9 - . _ ~ stay; every other byte is %XX, upper-case."""
    return quote(s, safe="")


def canonical_path(path):
    return "/" + "/".join(encode(unquote(s, errors="strict")) for s in path.split("/") if s)


def canonical_query(query):
    pairs = sorted((encode(k), encode(v)) for k, v in parse_qsl(query, keep_blank_values=True))
    return "&".join(f"{k}={v}" for k, v in pairs)


def signed_headers(method, target, body=b"", idempotency_key="", content_type="", timestamp=None, nonce=None):
    """The headers for one request to `target`. `timestamp` and `nonce` are for the test vectors only."""
    timestamp = timestamp or str(int(time.time()))
    nonce = nonce or secrets.token_urlsafe(24)  # 32 URL-safe characters
    url = urlsplit(target)
    message = "\n".join([
        "v1", method, canonical_path(url.path), canonical_query(url.query), timestamp, nonce, KEY_ID,
        idempotency_key, content_type, hashlib.sha256(body).hexdigest(),
    ])
    headers = {
        "BALBOA-Key": KEY_ID,
        "BALBOA-Timestamp": timestamp,
        "BALBOA-Nonce": nonce,
        "BALBOA-Signature": base64.b64encode(PRIVATE_KEY.sign(message.encode("utf-8"))).decode("ascii"),
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    if content_type:
        headers["Content-Type"] = content_type
    return headers


def call(method, target, body=None, idempotency_key=""):
    """One call. Never retried here: a retry is a new call, signed afresh."""
    raw = b"" if body is None else json.dumps(body, separators=(",", ":")).encode("utf-8")
    headers = signed_headers(method, target, raw, idempotency_key, "application/json" if raw else "")
    res = requests.request(method, BASE_URL + target, headers=headers, data=raw or None, timeout=10, allow_redirects=False)
    try:
        answer = res.json()
    except ValueError:  # an edge proxy's 502 or 504 is not JSON
        answer = None
    if not res.ok or not isinstance(answer, dict):
        a = answer if isinstance(answer, dict) else {}
        request_id = a.get("request_id") or res.headers.get("BALBOA-Request-Id") or "none: it never reached BALBOA"
        raise RuntimeError(f"{res.status_code} {a.get('reason') or a.get('code', 'not_json')}: {a.get('error', res.text[:200])} (request {request_id})")
    return answer

# page = call("GET", "/api/mm/v1/transactions?kind=deposit&limit=50")
# order = call("POST", "/api/mm/v1/mint-orders", {"amount": "250.00", "wallet": "settlement"}, idempotency_key="desk-42-mint-0001")

Pass the exact body bytes you send to signed_headers: a body re-serialised after signing — different spacing, key order or escaping — no longer matches its hash.

Trying it in Postman

The Postman collection has every endpoint below, with its parameters and an example body, and signs each request for you before it is sent. Its pre-request script uses the string above, the same code the API verifies with, and Ed25519. Your private key stays in Postman.

  1. Import the collection. It arrives with baseUrl set to this site's API host. Give your key in an environment of your own: keyId, and privateKey (the PEM file whole, or its 32 bytes in base64 or hex) as a secret, current value only. Current values are never synced or shared.

  2. Send Clock › Server time first. It is not signed. It shows whether your clock is right and the address you call from, which must be in your key's allowlist.

  3. Every POST gets a new Idempotency-Key on each send. To retry one safely, enable the request's Idempotency-Key header, set your own, and send it again.

A refusal reads as anywhere else (401 checklist). The collection follows no redirects, so a signed request is never sent anywhere else.

Clock sync

Every response carries the server's clock in BALBOA-Server-Time (unix seconds): read it from the answers you already get rather than asking for it. GET /api/mm/v1/time needs no key, and also tells you the address your calls come from:

{ "server_time": 1790000000, "iso": "2026-09-21T14:13:20.000Z", "window_seconds": 60, "your_address": "203.0.113.10" }

If your requests are refused for their timestamp and your clock is more than a few seconds away from the server's, fix the clock rather than adding an offset.

Responses and errors

Every response from BALBOA carries:

Header
BALBOA-Request-IdA UUID for this request. Quote it to BALBOA; it finds the call.
BALBOA-Server-TimeThe server's clock, unix seconds.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetYour key's budget for the minute, what is left, and when it resets (unix seconds) — on calls that authenticated.
Retry-AfterOn 429, some 503s, and a refusal for the day's room (key_limit_daily, account_limit_daily, platform_limit): seconds to wait — for those, until 00:00 UTC.

Money is always an exact decimal string ("250.00000000"), never a JSON number, and every time is ISO 8601 in UTC. An error is:

{ "error": "Authentication failed. Check the key, the signature and your clock, then sign a new request.", "code": "unauthorized", "request_id": "7c0e…" }

and, when the reason can be said (What is checked), it says it — reason, a message for a person in error, and what goes with it (server_time, your_address, key_status, missing):

{ "error": "This request came from 198.51.100.7, which is not in this key's IP allowlist.", "code": "unauthorized", "reason": "ip_not_allowed", "your_address": "198.51.100.7", "request_id": "7c0e…" }
StatuscodeMeaning
400invalid_requestA parameter or a field is not valid (the message says which).
400idempotency_key_required, idempotency_key_invalidA POST without an Idempotency-Key, or with one that is not 1–255 visible ASCII characters.
401unauthorizedAuthentication failed — see the checklist.
403insufficient_scopeThe key does not have the scope this needs.
403account_inactiveThe market-maker account is not active.
403verification_requiredThe account owner's verification needs renewing before money can move.
404not_foundNo such route, or no such transaction, order or redemption on your account.
405method_not_allowedThe route does not take this method.
409not_readyThe account is not set up for this yet: no settlement wallet, no source address — or, for a mint order or a redemption, no daily mint or redeem limit of its own yet (the message says which).
409idempotency_in_progressA request with this Idempotency-Key is still running — for seconds at most (see Idempotency).
409amount_matches_open_order, wallet_not_ready, destination_cooling, destination_unavailable, not_cancellable, transfer_on_its_waySee Minting and Redeeming.
413body_too_largeThe body is over 16 KB.
421wrong_hostThe API is not served on this host any more; host names the one to use.
422idempotency_key_reusedThis Idempotency-Key was used for a different request.
422key_limit_per_transaction, key_limit_daily, account_limit_daily, below_minimum, above_maximum, amount_below_fee, platform_limit, too_many_openThe limit stack.
422wallet_not_found, destination_not_allowed, insufficient_fundsSee Minting and Redeeming.
429rate_limitedOver a rate limit; wait Retry-After seconds.
500internal_errorOur fault. Retry with a new nonce; if it persists, send us the request id.
503unavailableNot available right now (a balance the chain did not return in time; minting or redeeming not running). Retry shortly.
503minting_disabled, redemptions_disabledBALBOA has paused minting, or redemptions. Nothing was made; try later.
503busyYour account was busy with another request. Nothing was made; retry with the same Idempotency-Key.

Not every answer is BALBOA's. A 502 or 504 from a load balancer or proxy between you and BALBOA, or a 404 from the web server for a path outside /api/mm/, may be HTML or empty, and carries no BALBOA-Request-Id — the call never reached the API. Parse defensively: treat a body that is not JSON as that, and do not look for a request id in it. The samples above do.

Rate limits, polling and automatic suspension

LimitDefault
Requests per minute, per key120
Requests per minute, per address (an IPv4 address, or an IPv6 /64), before any key is checked300

GET /api/mm/v1/account returns both (limits.requests_per_minute, limits.requests_per_minute_per_address).

Polling. Stay well inside the budget — about 20 calls a minute in all is plenty:

  • Transactions: ask for what changed since your last poll — GET /api/mm/v1/transactions?updated_since=<the time of your last poll, less a few seconds> — every 15 to 30 seconds, and page through with cursor. Follow a transaction that is not terminal by its ref only if you need it sooner.

  • Balances: every 30 to 60 seconds; each call reads the chain.

  • Account and settlement: when you start, and then every few minutes; they change rarely.

A key is suspended automatically when, within 10 minutes — counted from its approval, or from when it was last restored — it collects:

  • 5 requests from an address the key names whose signature did not verify;

  • 3 correctly signed requests from an address the key names that replayed a nonce;

  • 3 correctly signed requests, each with a new nonce, from an address outside its allowlist; or

  • 3 redemptions asked to an address that is not one of your usable destinations — not one of yours (destination_not_allowed), still in its waiting period (destination_cooling), or blocked (destination_unavailable). A key that leaked is tried on addresses you never registered; redeem only to a destination GET /settlement lists as ready.

Meeting your limits is not one: a refusal by the limit stack never suspends a key (BALBOA's staff are told when a key meets its own limits many times in an hour, and, apart, when a platform-wide cap is met).

Nothing else counts against the key: not a bad signature from an address it does not name (that counts against the address, which is refused for the rest of the window after 20), not a stale timestamp, not a request refused before its signature was checked, and nothing while the key waits for approval. A suspended key is refused until BALBOA restores it; your operations contact is emailed and messaged in the portal when it happens, with what to check. If you did not cause it, treat it as a sign your private key has leaked.

What a key already made goes on — mostly. Suspending, revoking or rotating a key stops new requests signed with it. What it made that is already moving carries on: a mint order a transfer is on its way to still mints when it confirms, and a redemption still settles and pays your own destination — each is your own money, going only where your account says. But when a key is suspended in a way that says it may be in someone else's hands — by your operations contact, by BALBOA's staff, or automatically for replays, calls from outside its allowlist or redemptions to addresses it may not use — its mint orders still waiting for their USDT are cancelled with it: an order someone else made must not decide where your next transfer goes. (A suspension for bad signatures, your own signing broken, cancels nothing.) The email and portal message about the suspension list what was cancelled and what is still open; the portal lists a key's open records before your operations contact confirms a suspension. To stop anything else, cancel it — with another key that has the scope, or in the portal — or ask BALBOA.

BALBOA may change these numbers.

Endpoints

RouteScope
GET /api/mm/v1/timenoneClock sync
GET /api/mm/v1/accountreadthe key, the account, limits and today's use
GET /api/mm/v1/balancesreadthe settlement wallet's BALBOA1, and each desk wallet's
GET /api/mm/v1/transactions, /transactions/:refreadeverything, newest first
GET /api/mm/v1/settlementreadwhere money goes in and out, and the terms
POST /api/mm/v1/mint-ordersmintmake a mint order (Minting)
GET /api/mm/v1/mint-orders, /mint-orders/:idreadyour mint orders
POST /api/mm/v1/mint-orders/:id/cancelmintcancel one still waiting for its transfer
POST /api/mm/v1/redemptionsredeemredeem BALBOA1 for USDT (Redeeming)
GET /api/mm/v1/redemptions, /redemptions/:idreadyour redemptions
POST /api/mm/v1/redemptions/:id/cancelredeemcancel one before its BALBOA1 is settled

Every answer is JSON. Your portal login also shows your keys and their limits, and lets your operations contact suspend one, under Settlement account.

GET /api/mm/v1/account

The API's "who am I": the key you signed with, and your account.

{
  "account": { "name": "Acme Liquidity Ltd", "kind": "market_maker", "status": "active", "opened_at": "2026-09-20T10:00:00.000Z", "settlement_wallet": "0x…" },
  "key": { "key_id": "bk_live_…", "environment": "live", "scopes": ["read", "mint", "redeem"], "ip_allowlist": ["203.0.113.10/32"], "expires_at": null },
  "limits": {
    "requests_per_minute": 120,
    "requests_per_minute_per_address": 300,
    "mint": {
      "daily_limit": "1000000.00000000", "used_today": "0.00000000", "remaining_today": "1000000.00000000",
      "ordered_today": "50000.00000000", "remaining_to_order": "950000.00000000", "max_per_order": "500000.00000000"
    },
    "redeem": { "daily_limit": "250000.00000000", "used_today": "25000.00000000", "remaining_today": "225000.00000000", "max_per_order": "100000.00000000" },
    "key": {
      "mint_per_transaction": "100000.00000000", "daily_mint": "500000.00000000",
      "mint_ordered_today": "50000.00000000", "mint_remaining_to_order": "450000.00000000",
      "redeem_per_transaction": "50000.00000000", "daily_redeem": "200000.00000000",
      "redeem_used_today": "25000.00000000", "redeem_remaining_today": "175000.00000000"
    }
  }
}

Days are UTC days. The account's own daily limits are always set for a market maker: no key may mint or redeem until they are. mint.daily_limit holds twice: on the mint orders you make each day — ordered_today, cancelled orders included, and remaining_to_order, which is what POST /mint-orders checks — and on the BALBOA1 minted each day (used_today, remaining_today: a deposit past it waits for BALBOA's staff). max_per_order is the largest one mint order or redemption may be — the same figure as /settlement's terms. The key limits are this key's own — the first layer of the limit stack — with what it has used of its daily ones today, counted the same way (a mint by what it ordered, cancelled orders included); null is none of its own, which a key holding mint or redeem never has for that scope. key.expires_at is when the key stops working — set once it has been replaced.

GET /api/mm/v1/balances

The settlement wallet's BALBOA1, read from the chain:

{ "wallet": "0x…", "token": "BALBOA1", "chain_id": 1, "balance": "1500.25", "reserved": "200.00000000", "available": "1300.25000000", "as_of": "2026-09-26T12:00:00.000Z" }

balance is exactly what the chain holds (up to 18 decimals); reserved is what your payments and redemptions have committed and not yet taken; available is what a new one may use, at 8 decimals. 409 not_ready while no settlement wallet is set up; 503 unavailable when the chain does not answer in time.

chains lists the same figures for each chain your account has a settlement wallet on — { "chain": "ethereum", "wallet", "balance", "reserved", "available" }, then "solana" once you have one there (its figures null when Solana did not answer in time). The top-level figures stay Ethereum's.

desks lists each of your desk wallets the same way — { "id": 3, "label": "MM-04", "status": "active", "chains": [ … ] }, its chains one entry for each chain it has a wallet on. Each desk's balance is its own: a redemption from a desk can use only what that desk holds.

GET /api/mm/v1/transactions

Newest first, a page at a time.

Parameter
kindComma-separated: deposit, mint_order, redemption, payment. Default: all.
limit1–100, default 25. Anything else is 400.
cursornext_cursor from the previous page.
updated_sinceOnly transactions whose updated_at is at or after this ISO 8601 UTC time (2026-09-26T12:00:00.000Z).
{
  "items": [
    {
      "ref": "deposit:12", "kind": "deposit", "reference": "Deposit #12", "status": "minted", "terminal": true, "direction": "in",
      "amount": "1000.00000000", "currency": "USDT", "usd_amount": "1000.00000000", "usd_indicative": false,
      "fee": "0.00000000", "fee_currency": "USDT", "expected_amount": null, "received_amount": null,
      "conversion_rate": null, "bank_reference": null,
      "created_at": "…", "updated_at": "…", "completed_at": "…",
      "steps": [{ "key": "received", "state": "done", "at": "…" }, { "key": "confirming", "state": "done", "at": "…" }, { "key": "minted", "state": "done", "at": "…" }],
      "hashes": [{ "key": "mint", "hash": "0x…", "chain_id": 1 }],
      "transfer": { "hash": "0x…", "chain_id": 1 }
    }
  ],
  "next_cursor": null
}

A deposit bound to a mint order appears once, as the order. status and steps are described below; terminal says nothing more will happen to it. A hash appears only once the transaction it names is final, which can be a little after its status says so.

GET /api/mm/v1/transactions/:ref

One transaction by its ref (payment:7, deposit:12, mint_order:3, redemption:5), as { "transaction": { … } }. 404 for anything that is not yours.

GET /api/mm/v1/settlement

Where money goes in and out, and on what terms:

{
  "deposit": { "address": "0x…", "chain_id": 1, "network": "Ethereum", "usdt_contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "confirmations": 12 },
  "settlement_wallet": "0x…",
  "source_addresses": ["0x…"],
  "redemption_destinations": [
    { "id": 4, "label": "Cold wallet", "address": "0x…", "status": "ready", "usable_from": "…", "created_at": "…" }
  ],
  "terms": {
    "mint": { "min": "10.00000000", "max": "500000.00000000", "fee_bps": 0, "fee_min": "0.00000000", "fee_currency": "USDT" },
    "redeem": { "min": "10.00000000", "max": "100000.00000000", "fee_bps": 0, "fee_min": "0.00000000", "fee_currency": "USDT" }
  }
}

deposits lists where USDT is deposited on each chain BALBOA takes it on — each with its chain ("ethereum" or "solana"): on Solana, address is the treasury wallet, usdt_contract is USDT's mint, chain_id is null, and a transfer counts once it is finalized. deposit is Ethereum's, as before. wallets gives your settlement wallet and source addresses on each chain, the same way; each redemption destination has its chain.

desks lists your desk wallets: { "id", "label", "status", "wallets": [{ "chain", "address" }] }, each usable once its status is "active".

USDT is credited only from source_addresses — on Solana, from the wallets in its entry of wallets, as their owner; from any other address it waits for BALBOA's staff. A redemption destination's status is ready, cooling (usable from usable_from) or unavailable. deposit is null if the deposit address is not configured. terms.*.max is the largest one order or redemption you may make: the platform's largest, cut — for a redemption — to what BALBOA's payout wallet sends in one transfer, and never more than the market makers' own daily cap for it, which no single order past it could fit. An order above it is refused above_maximum with that figure. terms.*.fee_bps and fee_min are your fees: those agreed for your account where BALBOA has set them, the platform's otherwise. A fee is fixed when it is charged — on a mint, when your transfer binds to its order; on a redemption, when it is made — so a change applies to what comes after.

GET /api/mm/v1/time

See Clock sync.

Before you mint or redeem

BALBOA sets these up with you; GET /settlement and GET /account show each.

  1. Your settlement wallet — where BALBOA1 is minted, and what a redemption burns from.

  2. Your USDT source addresses — the only addresses a transfer is credited from. USDT sent from any other address is not minted to you: it waits for BALBOA's staff. Send every mint's USDT from one of them.

  3. Your redemption destinations — the only addresses USDT is paid to. Only your operations contact adds one, in the portal (it confirms who they are first, and they are emailed); a new one is usable only after a waiting period (24 hours by default: usable_from on /settlement). The API cannot add or change one: redeem to one whose status is ready. Add one at least a day before you first redeem to it.

  4. Your account's daily limits — limits.mint.daily_limit and limits.redeem.daily_limit on /account, set by BALBOA. Both are set before any key may mint or redeem: they are your own, disclosed limits, which you meet before any platform-wide cap.

  5. The key's scopes and limits — mint and redeem, each with the key's own per-transaction and daily limits, and read to follow what it makes. On a live key, a scope added or a limit raised takes two BALBOA admins.

  6. Your desk wallets, if you want more than one wallet — see below.

Desk wallets

Beside your settlement wallet you may have desk wallets: one for each desk, strategy or book, each under a label of its own ("MM-04"). You mint to one by naming it as a mint order's wallet — "desk:3" — and redeem from one by naming it as a redemption's from. GET /settlement lists them with their ids; GET /balances gives each one's figures.

  • BALBOA sets them up. Send your BALBOA contact the label and the wallet's address on each chain. A desk is usable once a second BALBOA admin, not the one who registered its wallet, has approved it: its status reads "pending" until then, and "active" after. A wallet changed later goes back to "pending" the same way. A suspended desk reads "suspended".

  • Your limits are your account's. Every daily limit, and every key's, counts what all your wallets do together: more desks are never more room.

  • A desk's BALBOA1 is that desk's. A redemption from a desk uses only what that desk holds (422 insufficient_funds otherwise). Send money pays from the settlement wallet only.

  • USDT still comes from your source addresses. A desk's wallet need not be one of them; which wallet a transfer mints to is the order's.

  • A wallet that is not yours to name, or a desk that is not active, is refused: 422 wallet_not_found, 409 wallet_not_ready.

Minting

POST /api/mm/v1/mint-orders

Scope mint, an Idempotency-Key, and a JSON body:

Field
amountThe USDT you will send, as a decimal string to the cent: "50000.00". A JSON number is refused.
walletWhere the BALBOA1 is minted: "settlement", one of your desk wallets ("desk:3"), or the id of one of your clients (12, or "client:12"). Never an address: BALBOA1 is minted only to a wallet registered with BALBOA.
chainOptional: "ethereum" (the default) or "solana". The chain the USDT is sent on and the BALBOA1 minted on: your wallet there, and mint_order.deposit says where to send on it.

Any other field is refused (400 invalid_request), so a typo is never quietly ignored. With the Node.js sample above:

const { mint_order } = await call('POST', '/api/mm/v1/mint-orders',
  { amount: '50000.00', wallet: 'settlement' }, { idempotencyKey: 'desk-42-mint-0001' })
// send exactly mint_order.deposit.amount USDT from one of mint_order.deposit.source_addresses
// to mint_order.deposit.address, before mint_order.deposit.send_by

202 Accepted, with the order — a mint order is an instruction, not a mint:

{
  "mint_order": {
    "id": 42, "ref": "mint_order:42", "reference": "Mint order #42",
    "status": "awaiting_transfer", "terminal": false,
    "amount": "50000.00000000", "currency": "USDT",
    "wallet": { "kind": "settlement", "client_id": null, "desk_id": null, "address": "0x…" },
    "fee": "0.00000000", "fee_fixed": false, "receive_amount": "50000.00000000", "receive_currency": "BALBOA1",
    "received_amount": null, "review_required": false, "can_cancel": true,
    "deposit": {
      "address": "0x…", "chain_id": 1, "network": "Ethereum", "usdt_contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "confirmations": 12, "source_addresses": ["0x…"], "amount": "50000.00000000", "send_by": "2026-10-03T12:00:00.000Z"
    },
    "created_at": "…", "updated_at": "…", "expires_at": "…", "cancelled_at": null, "minted_at": null,
    "transfer": null, "hashes": [], "steps": [ … ],
    "api": { "key_id": "bk_live_…", "request_id": "7c0e…", "idempotency_key": "desk-42-mint-0001" }
  }
}

Then send exactly deposit.amount USDT from one of deposit.source_addresses to deposit.address, on deposit.network, before deposit.send_by. Once BALBOA's watcher has seen it deposit.confirmations blocks deep, it binds the transfer to the order — an order made before the transfer arrived, whose amount it matches exactly; otherwise none, and it is minted to your settlement wallet as a deposit of its own — and mints what arrived, less the fee, to the order's wallet. An order made through the API takes a transfer only for its exact amount, never as the only one open (an order made in the portal, alone, takes any amount): a key that leaked could otherwise order a little to a client's wallet and capture your next transfer, whatever its size. See Reconciliation and outcomes for every case. What happens on the way:

  • over the approval threshold (review_required, 100,000 USDT by default), two BALBOA admins approve the deposit first — in_review, usually within one business day;

  • past your account's daily mint limit, past the market makers' daily mint cap, or held by any of BALBOA's guards, it waits for staff — under_review;

  • when the treasury's daily mint capacity is used up, it waits for room — scheduled: it mints on its own, usually after 00:00 UTC.

Your key's limits bound what you may order — every order made in the day, a cancelled one too, so making and cancelling orders spends the day's room. What is minted is what arrives: send the amount you ordered. The fee is fixed on what arrives.

Two open orders for the same amount could not be told apart by the transfer that pays one, so the second is refused (409 amount_matches_open_order): vary the amount, even by a cent. At most five orders may be open at once (422 too_many_open); an order unpaid for 7 days expires (not_funded). Other refusals: 422 wallet_not_found (not settlement or one of your clients), 409 wallet_not_ready (a client pending or paused, or no wallet), 409 not_ready (no source address registered).

GET /api/mm/v1/mint-orders/:id

One of your orders, as above, as it stands. 404 for anyone else's.

GET /api/mm/v1/mint-orders

Your orders, newest first — made through the API or in the portal — as { "items": [ … ], "next_cursor": … }.

Parameter
limit1–100, default 25.
cursornext_cursor from the previous page.
statusComma-separated statuses: status=awaiting_transfer,confirming.
updated_sinceOnly orders whose updated_at is at or after this ISO 8601 UTC time.
key_idOnly those made with this key of yours.

With status, a page may hold fewer than limit items, or none: read on while next_cursor is not null.

POST /api/mm/v1/mint-orders/:id/cancel

Scope mint, an Idempotency-Key, no body. Cancels an order still waiting for its transfer, and answers it (200). Refused while a transfer is on its way to it (409 transfer_on_its_way: it counts as the order says), and once its transfer has bound or it has expired (409 not_cancellable). Cancelling one already cancelled answers the same again.

Redeeming

POST /api/mm/v1/redemptions

Scope redeem, an Idempotency-Key, and a JSON body:

Field
amountBALBOA1 to redeem, as a decimal string to the cent: "25000.00".
destinationOne of your redemption destinations: its id (from GET /settlement), or its exact address — on Solana, exactly as spelled.
fromOptional: the wallet the BALBOA1 is burned from — "settlement" (the default) or one of your desk wallets, "desk:3". Never an address.
chainOptional. A redemption is made on its destination's chain: the BALBOA1 burned from your settlement wallet there, the USDT paid there. If you send chain, it must be the destination's (400 invalid_request otherwise).

The destination must be yours, not removed, past its waiting period and not blocked — otherwise 422 destination_not_allowed, 409 destination_cooling (with usable_from) or 409 destination_unavailable; each of these counts towards suspending the key (see automatic suspension). The settlement wallet must hold the BALBOA1 free — less what your payments and redemptions have already committed (422 insufficient_funds).

const { redemption } = await call('POST', '/api/mm/v1/redemptions',
  { amount: '25000.00', destination: 4 }, { idempotencyKey: 'desk-42-redeem-0001' })

202 Accepted, with the redemption as it stands — it is taken forward at once:

{
  "redemption": {
    "id": 7, "ref": "redemption:7", "reference": "Redemption #7",
    "status": "in_review", "terminal": false,
    "amount": "25000.00000000", "currency": "BALBOA1", "fee": "0.00000000", "fee_currency": "USDT",
    "payout_amount": "25000.00000000", "payout_currency": "USDT",
    "destination": { "id": 4, "label": "Cold wallet", "address": "0x…" },
    "from": { "kind": "settlement", "desk_id": null, "address": "0x…" },
    "review_required": true, "can_cancel": true,
    "created_at": "…", "updated_at": "…", "settled_at": null, "paid_at": null, "completed_at": null, "cancelled_at": null, "rejected_at": null,
    "hashes": [], "steps": [ … ],
    "api": { "key_id": "bk_live_…", "request_id": "7c0e…", "idempotency_key": "desk-42-redeem-0001" }
  }
}

Your BALBOA1 is burned from the settlement wallet — or the desk wallet from names; only once that burn is final is the USDT — payout_amount, the amount less the fee — sent to the destination, once. Over the review threshold (10,000 by default) an admin approves it first (in_review, usually within one business day). Past a daily limit or cap — yours, your key's, the market makers', or the treasury's — it waits (scheduled), counted on the day it goes and checked again then; while BALBOA's payout wallet cannot pay it yet, waiting_liquidity; held by its destination or the account, on_hold. hashes carries the settlement (settlement) and the USDT transfer (payout) once each is final. Reconciliation and outcomes says which statuses come before the burn and which after.

GET /api/mm/v1/redemptions/:id, GET /api/mm/v1/redemptions

One of yours, and the list — with the same parameters as the mint orders'.

POST /api/mm/v1/redemptions/:id/cancel

Scope redeem, an Idempotency-Key, no body. Cancels a redemption before its BALBOA1 is settled — in review, processing, scheduled, on hold before the burn, or a burn that did not go through; after, 409 not_cancellable (the USDT is on its way to you).

Idempotency

Every POST carries an Idempotency-Key — 400 idempotency_key_required without one — 1 to 255 visible ASCII characters (a UUID, or your own order id). It is part of the string you sign. Use a new key for each thing you mean to do, and the same key when you retry that thing — after a timeout, a dropped connection, a 5xx. Keys are your account's, scoped to the route: the same Idempotency-Key sent through any of your keys is the same request — a retry through a replacement key, or through your desk's second key, never makes a second order or redemption — and another market maker's keys never meet yours. The key you sign with must still hold the route's scope: that is checked before anything is replayed.

You sendYou get
a key for the first timethe request is made; its answer is kept for 7 days
the same key, the same body, again — through any of your keysthe first answer again, the same status and body, with Idempotent-Replayed: true — nothing is made a second time
the same key, another body (or another order's /cancel)422 idempotency_key_reused; nothing is made
the same key while the first is still running409 idempotency_in_progress; nothing is made — wait, then read the result or retry with the same key

A key is recorded in the same database transaction as the order or redemption it made, never before it. So 409 idempotency_in_progress lasts only as long as the first request's own work — seconds; often the duplicate simply waits and hears the first answer as a replay — never a refusal the first one caused, such as the day's room it took. And a request that dies part-way — a timeout on our side, a crash, a restart — leaves nothing behind: its retry with the same key makes the record, once. There is no key stuck "in progress" to wait out.

A request that was refused keeps nothing: fix it, and the same key may be sent again. The same body is the same JSON, whatever its key order or spacing. A retry is still a new request to sign — a new timestamp and nonce, the same Idempotency-Key.

Never use a new key for a retry of a request whose answer you did not get: that is how an order is made twice. If you cannot tell whether a request arrived, send it again with the same key, or look for it with GET /mint-orders?key_id=… (each record says the request_id and idempotency_key that made it, under api).

The limit stack

Every mint order and redemption is checked against these, in this order, and refused at the first it does not fit — each with its own code. Every amount is exact, and every day is the UTC day: a mint order counts on the day it is made — a cancelled one too, so that making and cancelling orders spends the room it tests; a redemption on the day its BALBOA1 is taken for settlement (and one not yet taken, today — a rejected or cancelled one never). Two requests at once are counted one after the other: none can take a day past a limit.

#LayercodeStatusTold
1The key's own limit for one transactionkey_limit_per_transaction422limit
1The key's own daily limitkey_limit_daily422limit, and ordered_today, remaining_to_order (a mint) or used_today, remaining_today (a redemption); resets_at
2Your account's daily mint or redeem limitaccount_limit_daily422the same as the key's
2Your account's daily limit not setnot_ready409
3The smallest mint order or redemptionbelow_minimum422min
3The largest you may make (terms.*.max on /settlement)above_maximum422max
3A fee that would leave nothingamount_below_fee422
4The account active, a market maker, its owner's login activeaccount_inactive403
4The owner's verification in standingverification_required403
4Minting, or redemptions, switched on by BALBOAminting_disabled, redemptions_disabled503
4Minting or redeeming running now (the operator, the payout wallet)unavailable503
4The platform's daily caps: every market maker's orders together; every market maker's redemptions and payments together; every account's redemptionsplatform_limit422resets_at — never a figure
4Your open mint orders, or redemptions on their waytoo_many_open422max_open
5The treasury's daily mint and burn capacity——nothing is refused: a burn or a mint that does not fit today waits, scheduled
6The BALBOA1 contract (paused, a blacklisted address)——the settlement or the mint fails, and the record says so (needs_attention, under_review)

A refusal for the day's room — key_limit_daily, account_limit_daily, platform_limit — carries resets_at, the next 00:00 UTC, and a Retry-After header in seconds until then. GET /settlement lists the smallest and largest (terms), and GET /account the key's and the account's limits and what is used of them today — remaining_to_order is what a new mint order is checked against. The largest is never more than the market makers' own daily cap: an order past it could never fit, and is refused above_maximum with the figure, not platform_limit. A platform_limit says nothing of how much the platform has done, by design (the caps' values are no secret; others' use of them is): try again after resets_at. Meeting a limit never suspends a key.

Polling mint orders and redemptions

  • After a POST, keep the id (or read ref), and follow it with GET /mint-orders/:id or GET /redemptions/:id — every 15 to 30 seconds while it moves, less often while it waits (awaiting_transfer, in_review, scheduled, on_hold, waiting_liquidity) — until terminal is true.

  • Many at once: poll the list with updated_since=<your last poll, less a few seconds> (and status= to narrow it), rather than each one. A record's updated_at moves whenever what it tells you can: a mint order's when its transfer is seen, and when its deposit moves after binding (confirmed, in review, minting, minted, held, refunded); a redemption's when its status or its reason changes (processing to scheduled, one scheduled wait to another). It may also move with nothing new to show: treat it as "look again", never as "something changed".

  • A mint order's transfer takes deposit.confirmations blocks — some three minutes on Ethereum for 12 — before anything is minted.

  • Stay inside the polling budget: about 20 calls a minute in all is plenty.

Reconciliation and outcomes

Matching a transfer to an order. A mint order carries, once its USDT is seen, transfer.hash (your transaction) and received_amount (what arrived). Match on the hash; received_amount is what BALBOA1 is minted for, less the fee. hashes carries the mint (mint) once it is final.

A transfer that binds to no order is still yours: it is minted to your settlement wallet as a deposit of its own — GET /transactions?kind=deposit shows it, with its transfer.hash. It happens when:

  • its amount matches no open order exactly and two or more are open (with one open, made in the portal, that one takes it whatever the amount);

  • the only open order was made through the API — those take a transfer only for their exact amount;

  • you split one order's USDT into two transfers (neither matches);

  • it arrives after the order's send_by, or before the order was made (an order never takes a transfer that arrived before it).

Watch /transactions?kind=deposit alongside your orders, and cancel the order a transfer did not bind to, so it cannot take a later one. USDT from an address that is not one of your source_addresses is not minted at all: it waits for BALBOA's staff (write to support with its hash).

When a mint order ends without a mint. rejected: BALBOA's staff rejected its deposit (a check failed); refunded (USDT returned): the USDT went back to the address it came from — a rejected deposit, or one too small to cover its fee — and hashes carries the refund (refund). not_funded: nothing arrived by send_by; cancelled: you, or a key's suspension, cancelled it before its transfer. Nothing is ever minted to an address you did not register.

Redemptions: before the burn, and after. Before the burn your BALBOA1 is still in your wallet: in_review and scheduled, which you may cancel, and processing — cancellable until the burn is claimed, a moment before it is sent. After it, the USDT is owed to you and cannot be cancelled: sending, sent, completed, waiting_liquidity, returning. on_hold, on_pause and needs_attention can fall either side — read settled_at (set once the burn is final) and can_cancel, never the status alone. returned: BALBOA gave the BALBOA1 back to your settlement wallet instead of paying USDT (the payout could not be made, and two BALBOA admins agreed); hashes carries the return (return). At needs_attention nothing more happens on its own: write to support with the redemption's ref — if the burn is final (settled_at), your USDT is paid by hand or the BALBOA1 returned; if not, cancel it or ask BALBOA to retry.

Hashes. Each record's hashes names what each is: mint (BALBOA1 minted to you), settlement (your BALBOA1 burned for a redemption), payout (the USDT sent to your destination), refund (your USDT sent back), return (your BALBOA1 given back). A hash appears once the transaction is final.

How long reviews take. A redemption over 10,000 BALBOA1 waits for one BALBOA admin; a deposit over 100,000 USDT for two — each usually within one business day, and the admins are emailed when one starts waiting. These are the defaults; review_required on the record says whether yours will.

Transaction statuses and steps

A transaction's status is one of these, by kind; a terminal status is the last it will have. New statuses may be added (see Compatibility): treat one you do not know as not terminal.

Deposits (deposit)

statusMeansTerminal
confirmingConfirmingno
processingProcessingno
mintedMintedyes
in_reviewIn reviewno
under_reviewIn reviewno
not_on_chainNot on chainyes
rejectedRejectedyes
refundedUSDT returnedyes
scheduledScheduledno

Mint orders (mint_order)

statusMeansTerminal
awaiting_transferWaiting for your transferno
confirmingConfirmingno
issuingIssuing BALBOA1no
scheduledScheduledno
in_reviewIn reviewno
under_reviewIn reviewno
mintedMintedyes
rejectedRejectedyes
refundedUSDT returnedyes
cancelledCancelledyes
not_fundedExpiredyes

Payments (payment)

statusMeansTerminal
in_reviewIn reviewno
awaiting_fundsAwaiting fundsno
processingProcessingno
requestedRequestedno
burnedDebitedno
convertingConverting to USDno
convertedConverted to USDno
deliveredDeliveredyes
needs_attentionNeeds attentionno
rejectedRejectedyes
cancelledCancelledyes
on_holdOn holdno
scheduledScheduledno
not_fundedExpiredyes

Redemptions (redemption)

statusMeansTerminal
in_reviewIn reviewno
processingProcessingno
sendingSending USDTno
sentUSDT sentno
completedCompletedyes
cancelledCancelledyes
rejectedRejectedyes
needs_attentionNeeds attentionno
returningReturning BALBOA1no
returnedReturnedyes
on_holdOn holdno
scheduledScheduledno
on_pausePausedno
waiting_liquidityWaiting for liquidityno

steps is the transaction's timeline, in order: each step's key, its state — done, current, upcoming, attention (it waits on something), failed or ended (the transaction stopped there) — and when it was done.

KindStep keys
depositreceived, confirming, minted, returned, rejected
mint_ordercreated, received, confirming, minted, returned, cancelled, rejected
paymentcreated, settlement, redemption, bank, delivered, cancelled, rejected
redemptioncreated, settlement, sent, completed, cancelled, rejected, closed

Compatibility and versioning

Within v1 — the paths under /api/mm/v1/ and the v1 string you sign — BALBOA only makes changes an integration written to this guide keeps working through:

  • new fields in an answer, and new optional parameters;

  • new values where a list of values is given: a transaction status, a step key or state, an error code or reason, a kind;

  • new endpoints.

So ignore fields you do not know, and treat an unknown value as its safe case (an unknown status: not terminal). Anything that would break an integration — a field removed or renamed, a meaning changed, a new rule about what you sign — is v2, announced to your operations contact at least 90 days ahead, with v1 served beside it until then. A security fix may be made sooner, and you would be told at once.

Changelog

  • 2026-10-19 — Desk wallets. Beside your settlement wallet you may have desk wallets, each under a label of its own (Desk wallets): mint to one with a mint order's wallet: "desk:<id>", redeem from one with a redemption's new optional from. GET /settlement and GET /balances add desks; a mint order's wallet adds desk_id, and a redemption adds from. An integration that names no desk works as before.

  • 2026-10-19 — Fees per account. BALBOA may agree mint and redeem fees with your account that differ from the platform's. GET /settlement's terms, GET /account, every quote and every order carry yours. Nothing about the API's shape changed.

  • 2026-10-08 — Solana in the sandbox. Where the sandbox offers Solana it is on devnet, with Circle's devnet USDC as its USDT there (The sandbox → On Solana).

  • 2026-10-08 — Solana. BALBOA1 is on Ethereum and Solana. Every mint order, redemption, destination and transaction has a chain ("ethereum" or "solana"); a mint order takes an optional chain (Ethereum when you send none), and a redemption is made on its destination's chain. GET /settlement adds deposits (where to send USDT on each chain) and wallets (your settlement wallet and source addresses on each); GET /balances adds chains. Nothing that was there changed: an integration that sends no chain works as before, on Ethereum.

  • 2026-10-07 — A Postman collection (Trying it in Postman): every endpoint, with each request signed for you by its pre-request script. It uses the same canonical string as the API and Ed25519, with your own key, which stays in Postman. Nothing about the API changed.

  • 2026-09-26 — The sandbox: a deployment of its own on Sepolia, at https://api-sandbox.<domain>, with bk_test_ keys — working as soon as they are issued — and test USDT anyone can mint, to integrate and test minting and redeeming before production. BALBOA sets up your sandbox login and account from your contact's email, a source address and your public key — there is no sign-up. Fewer confirmations and a shorter wait for new destinations than production; test balances can be changed by others until its contracts move to a Safe of its own; it may be reset. The portal's Test funds page, and The sandbox, with the whole way from a key to a first mint and redemption.

  • 2026-09-26 — Mint and redeem. POST /mint-orders (deposit-backed: BALBOA1 is minted only once your USDT arrives from a registered source address; an order made through the API takes a transfer only for its exact amount), POST /redemptions (to your registered destinations only), each with its GET, list and /cancel. The mint and redeem scopes, granted only with the key's own limits and once your account's own daily limits are set; a money key needs read to follow what it makes. An Idempotency-Key on every POST, your account's — any of your keys retrying a request gets its first answer — recorded with the record it made, so a request that dies part-way leaves nothing to wait out. The limit stack and its codes; a mint's day counts every order made, cancelled ones too; daily refusals and platform_limit carry resets_at and Retry-After; the largest order you may make is terms.*.max, and one above it is above_maximum. A fourth automatic suspension, for redemptions to addresses a key may not use; a suspension that says a key may be in someone else's hands cancels its mint orders still waiting for USDT. /account shows the key's limits and today's use, the account's ordered_today and remaining_to_order, and max_per_order. A mint order or deposit waiting for the treasury's daily capacity is scheduled. updated_since follows a mint order's deposit and a redemption's reason. Reconciliation and outcomes. Test vector 4, a signed POST /mint-orders.

  • 2026-09-26 — v1 before anyone has integrated: the string you sign now takes the path and query in canonical form (decoded, encoded again, the query sorted) instead of exactly as sent, and signs the Idempotency-Key and Content-Type headers. Refused calls say why, where that gives nothing away (reason). GET /time answers your_address; /account the per-address limit; transactions carry terminal, and take updated_since; limit over 100 is refused rather than cut. X-RateLimit-Reset added. A bad signature counts against a key only from an address it names. The 421 wrong_host answer.

  • 2026-09-22 — First version: read-only v1.