Stabletrust API

Agents that pay each other onchain expose every invoice, fee, and settlement to the public. The Stabletrust API lets an agent or backend service hold an encrypted balance and pay other accounts without revealing amounts, using plain HTTP requests. There is no SDK to install and no proof generation in your runtime: the API wraps the @fairblock/stabletrust SDK and handles key derivation, zero-knowledge proofs, and transaction submission for you. Base URL

https://stabletrust-api.fairblock.network

All endpoints accept and return JSON. Amounts and balances are encrypted onchain; wallet addresses stay visible.

Quickstart

Shield 10 USDC into a confidential account on Base Sepolia:

const res = await fetch("https://stabletrust-api.fairblock.network/deposit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    privateKey: process.env.AGENT_KEY,
    tokenAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia
    amount: "10000000", // 10 USDC (6 decimals)
    chainId: 84532, // Base Sepolia
  }),
});

console.log(await res.json());
// { success: true, message: "Deposit successful", tx: "0x..." }

curl -X POST https://stabletrust-api.fairblock.network/deposit \
  -H "Content-Type: application/json" \
  -d '{
    "privateKey": "'"$AGENT_KEY"'",
    "tokenAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "amount": "10000000",
    "chainId": 84532
  }'

The wallet pays gas for every operation, so it needs the chain’s native token (for example, Base Sepolia ETH) in addition to the tokens it deposits. On mainnet (Arbitrum One, Base, and Ethereum), transfers and withdrawals also charge a protocol fee in ETH.

How it works

Create accounts

POST /account/create provisions the wallet’s confidential account. It’s idempotent, so it’s safe to call every time. A recipient must have an account before it can receive a transfer. Deposit, transfer, and withdraw create the caller’s own account automatically if it’s missing.

Deposit

POST /deposit moves public ERC-20 tokens from the wallet into its confidential account. The balance is now encrypted onchain.

Transfer

POST /transfer sends tokens to another confidential account. The amount is hidden onchain, and the funds arrive in the recipient’s pending balance.

Apply (optional)

POST /apply moves received funds from pending to available. Deposit, transfer, and withdraw already apply pending funds automatically when they need them, so call this when you want to settle received funds explicitly, for example before checking a balance.

Withdraw

POST /withdraw moves tokens from the confidential balance back to the wallet as public ERC-20.

Check a balance at any time with POST /balance. It’s read-only and sends no transaction.

Request fields

These fields are shared across endpoints:

Field	Type	Description
`privateKey`	string	Private key of the wallet that owns the confidential account. Used to sign transactions and to derive the account’s decryption key.
`chainId`	number	Target chain. See Supported chains.
`tokenAddress`	string	ERC-20 token contract address. The token must be supported by Stabletrust on that chain.
`amount`	string	Amount in the token’s base units, for example `"10000000"` = 10 USDC (6 decimals). Pass it as a string to avoid precision loss; a number is also accepted.
`waitForFinalization`	boolean	Optional, default `true`. When `true`, the API responds after the encrypted balance update is finalized. When `false`, it responds as soon as the transaction is mined, and the encrypted balance updates shortly after.

Confidential balances keep 2 decimal places, so the smallest amount is 0.01 of a token ("10000" for USDC). Amounts with more precision are rounded down to 2 decimal places, and amounts below 0.01 are rejected.

Endpoints

`POST /account/create`

Provisions the wallet’s confidential account if it doesn’t exist yet. Idempotent.

Field	Required
`privateKey`	yes
`chainId`	yes
`waitForFinalization`	no (default `true`)

const res = await fetch("https://stabletrust-api.fairblock.network/account/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ privateKey: process.env.AGENT_KEY, chainId: 84532 }),
});

{
  "success": true,
  "address": "0x...",
  "created": true,
  "message": "Account created successfully"
}

If the account already exists, created is false and message is "Account already exists".

`POST /deposit`

Moves public ERC-20 tokens from the wallet into its confidential account. The wallet must hold the tokens.

Field	Required
`privateKey`	yes
`tokenAddress`	yes
`amount`	yes
`chainId`	yes
`waitForFinalization`	no (default `true`)

{
  "success": true,
  "message": "Deposit successful",
  "tx": "0x..."
}

`POST /transfer`

Sends tokens confidentially to another account. The recipient must already have a confidential account.

Field	Required
`privateKey`	yes
`recipientAddress`	yes
`tokenAddress`	yes
`amount`	yes
`chainId`	yes
`useOffchainVerify`	no (default `false`). When `true`, the zero-knowledge proof is stored off-chain on Stabletrust’s IPFS storage and only its reference is submitted onchain, instead of the full proof.
`waitForFinalization`	no (default `true`)

const res = await fetch("https://stabletrust-api.fairblock.network/transfer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    privateKey: process.env.AGENT_KEY,
    recipientAddress: "0xRecipientAddress",
    tokenAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    amount: "5000000", // 5 USDC
    chainId: 84532,
  }),
});

{
  "success": true,
  "message": "Transfer successful",
  "tx": "0x..."
}

`POST /apply`

Moves the wallet’s pending balance (received funds) to its available balance.

Field	Required
`privateKey`	yes
`chainId`	yes
`waitForFinalization`	no (default `true`)

{
  "success": true,
  "message": "Pending balance applied",
  "tx": "0x..."
}

If the wallet has no confidential account, the API returns 400 with "No confidential account for this wallet; create one first".

`POST /withdraw`

Moves tokens from the confidential balance back to the wallet as public ERC-20.

Field	Required
`privateKey`	yes
`tokenAddress`	yes
`amount`	yes
`chainId`	yes
`useOffchainVerify`	no (default `false`). Same as for `/transfer`.
`waitForFinalization`	no (default `true`)

{
  "success": true,
  "message": "Withdrawal successful",
  "tx": "0x..."
}

`POST /balance`

Decrypts and returns the confidential balance. Read-only: it sends no transaction and never creates an account.

Field	Required
`privateKey`	yes
`tokenAddress`	yes
`chainId`	yes
`address`	no. Defaults to the wallet derived from `privateKey`. A balance can only be decrypted with its owner’s key, so query the wallet’s own address.

const res = await fetch("https://stabletrust-api.fairblock.network/balance", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    privateKey: process.env.AGENT_KEY,
    tokenAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    chainId: 84532,
  }),
});

{
  "success": true,
  "address": "0x...",
  "tokenAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "exists": true,
  "balance": {
    "total": "10000000",
    "available": "10000000",
    "pending": "0"
  }
}

Balances are strings in the token’s base units. If the account hasn’t been created yet, exists is false and every balance is "0".

`GET /health`

Checks that the API is up.

{ "message": "API is healthy" }

Errors

Status	When	Body
`400`	A required field is missing	`{ "error": "chainId is required" }`
`400`	`/apply` on a wallet with no confidential account	`{ "success": false, "error": "No confidential account for this wallet; create one first" }`
`429`	More than 30 requests per minute from the same IP	`{ "success": false, "error": "Too many requests, please try again later." }`
`500`	The operation failed, for example insufficient balance, a recipient without an account, or an RPC error	`{ "success": false, "error": "<reason>" }`

Supported chains

Chain	Chain ID	Network
Arbitrum One	`42161`	Mainnet
Base	`8453`	Mainnet
Ethereum	`1`	Mainnet
Base Sepolia	`84532`	Testnet
Ethereum Sepolia	`11155111`	Testnet
Arbitrum Sepolia	`421614`	Testnet
Arc Testnet	`5042002`	Testnet
Stable Testnet	`2201`	Testnet

See Supported Networks for the Stabletrust contract on each chain.

Self-hosting

The API is open source at github.com/Fairblock/stabletrust-api. Run it yourself to keep private keys inside your own infrastructure:

git clone https://github.com/Fairblock/stabletrust-api.git
cd stabletrust-api
npm install
npm start

It listens on PORT (default 3000). Optional environment variables:

Variable	Purpose
`PORT`	Port to listen on. Default `3000`.
`RPC_URL_<chainId>`	Override the RPC endpoint for a chain, for example `RPC_URL_84532`.
`CONTRACT_ADDRESS_<chainId>`	Use a specific Stabletrust contract on a chain. To add a chain that isn’t built in, such as a local devnet, set both `RPC_URL_<chainId>` and `CONTRACT_ADDRESS_<chainId>`.

Best practices

Use a dedicated agent wallet funded with only what the agent needs, since its private key travels with every request.
Create the recipient’s account first. A transfer to an address without a confidential account fails.
Check the available balance with /balance before transferring or withdrawing.
Retry transient failures. Retry 500 errors caused by network or RPC issues, and back off when you receive 429.

When to use the SDK instead

The API performs standard confidential transfers: amounts and balances are hidden, but wallet addresses are visible onchain. Use the SDK directly if you want private keys to stay in your own runtime, or if you need to hide the sender’s address with unlinkable transfers.

Build an App with the SDK

Use the @fairblock/stabletrust SDK directly in your app or agent runtime.

Unlinkable Transfers

Hide the sender’s address as well as the amount.

Get Started

Confidential Assets and Transfers

Protected Execution

API Reference

Resources

Quickstart

How it works

Request fields

Endpoints

`POST /account/create`

`POST /deposit`

`POST /transfer`

`POST /apply`

`POST /withdraw`

`POST /balance`

`GET /health`

Errors

Supported chains

Self-hosting

Best practices

When to use the SDK instead

Build an App with the SDK

Unlinkable Transfers

​Quickstart

​How it works

​Request fields

​Endpoints

​POST /account/create

​POST /deposit

​POST /transfer

​POST /apply

​POST /withdraw

​POST /balance

​GET /health

​Errors

​Supported chains

​Self-hosting

​Best practices

​When to use the SDK instead

Build an App with the SDK

Unlinkable Transfers

Quickstart

How it works

Request fields

Endpoints

`POST /account/create`

`POST /deposit`

`POST /transfer`

`POST /apply`

`POST /withdraw`

`POST /balance`

`GET /health`

Errors

Supported chains

Self-hosting

Best practices

When to use the SDK instead