Environments and API keys
The pilot base URL, what is real and what is simulated in it, and how your API keys are issued, stored, rotated and revoked.
Base URL
There is one environment. Every call in these docs goes to it.
| Environment | Base URL |
|---|---|
| Pilot | https://api.threecommabank.com/api/partner/v1 |
Set it once and read it from your configuration:
export TCB_API_BASE="https://api.threecommabank.com/api/partner/v1"
export TCB_API_KEY="test_..."What is real and what is not
Read the disclosure above as part of the contract, not as a caveat. Here is what it means when you write code against this environment.
| Area | In the pilot |
|---|---|
| Fiat in and out | Mocked. A deposit debits a ledger entry against a sandbox provider; no money leaves or reaches a real bank, and no IBAN you are issued receives a real payment. |
| The vault and your shares | Real contracts, on a testnet (Arbitrum Sepolia). Vault deposits and withdrawals are real on-chain transactions and return real transaction hashes. |
| Yield | Simulated. The share price rises because the rate is set administratively, not because capital was deployed. Treat the figures as correctly shaped, not as a return. |
| Conversion rates | A quote from an external venue, or no conversion. When no venue can price a pair the request is refused with 503 PRICING_UNAVAILABLE; nothing is priced from an internal table. Read rate.pricingModel on every conversion before displaying the rate. |
| Webhooks | Real. Events are signed, retried and rotatable exactly as they will be later. |
| Crypto deposits | Real arrivals on the testnet. An address you are issued accepts USDC on Arbitrum Sepolia only; anything else sent to it is recorded and held, not credited. |
| Payouts | The full control path runs — screening, TCB approval, the holding period on a destination — and the sandbox rail settles the payment. No real bank receives it. |
| Custody | TCB holds your vault shares, and any tcbUSD you hold, in the TCB wallet assigned to you. You hold no keys; each sub-account's shares and tcbUSD are book entries against what that wallet holds. |
One thing settles instantly: a within-tree transfer (POST /transfers) commits
atomically and is terminal on the response. An inbound payment to an issued
IBAN never happens, and no real customer money ever moves.
No production environment
There is no mainnet deployment and no production tier. Build and test against the pilot, and contact TCB before you plan a launch date.
API key shape
A key is an environment prefix, an underscore, and 43 URL-safe characters:
test_A7fQ2xMhk4Rr9vN1sT6yUwPzB3dJcL8eKmXn0oQaZi5The first twelve characters (test_A7fQ2xM) are the key prefix. It is not
secret. Log it, quote it in support requests, and use it to tell which key a
running integration is holding. GET /me returns it as keyPrefix.
Prefixes and what the environment tag changes
| Prefix | Tier |
|---|---|
test_ | Sandbox |
stg_ | Staging |
The tag labels the key. It does not route it. Nothing in the request path
branches on it. GET /me reports it as environment, so a startup check can
assert that a process holds the key you meant to give it. That is what the
tag is good for today. test_ and stg_ are the two prefixes you may
receive; TCB tells you which you hold.
Issuance, rotation and revocation
Keys are issued, rotated and revoked by TCB. There is no self-serve key API and no key management UI: you cannot mint a key and you cannot revoke your own. Contact partners@threecomma.group for all four of these:
| Ask for | What happens |
|---|---|
| A new key | You receive a key with an agreed scope list. See Authentication. |
| A scope change | Your existing key's scopes are edited in place; the secret does not change. |
| A rotation | A new secret is issued and the old key is revoked in the same instant. Name, scopes, expiry and any sub-client restriction carry over unchanged. |
| A revocation | The key stops working immediately and permanently. |
The secret is shown exactly once
The full key is displayed at issuance and never again. TCB stores only a hash of it and cannot recover it for you. If you lose it, the only remedy is a rotation, which invalidates the key you lost.
Rotation has no overlap window. The old key stops working the moment the new one exists. Deploy the new secret before you ask for the rotation, or plan for a gap. Webhook signing secrets behave differently: those rotate with an overlap, and both signatures verify during it. See the webhooks guide.
Storing the key
- Keep it in your secret manager, never in source control, a container image, a build log or a front-end bundle.
- The key authenticates your whole tree. Anything holding it can act as you, within its scopes.
- Give each deployment its own key where you can, so a rotation is scoped to
one system and the
keyPrefixin your logs tells you which one acted. - Never send it from a browser or a mobile app. This API is server-to-server.
Expiry
A key may carry an expiry date. TCB tells you at issuance whether yours does.
An expired key stops authenticating and cannot be renewed; it is replaced. An
expired key returns 401, the same response an invalid key gets.
What you cannot do in the pilot
- There is no production or mainnet environment.
- There are no simulation or test-fixture endpoints: nothing lets you force a deposit to fail, advance the clock, or fabricate an inbound payment.
- There is no self-serve sandbox to sign up for, and no SDK. Call the HTTP API directly.
- There is no status page.
Authentication
Bearer tokens, scopes, and acting on behalf of a sub-client.
Quickstart
Check your key and make your first deposit.