Skip to main content

​
POST /accounts

Register an account commitment on-chain. Must be called before an account can send or receive transfers.

​
What an account commitment is

An account commitment is H(wallet_address) — a one-way hash of the wallet address. It is the public on-chain identifier for an account. The wallet address itself never appears on-chain or in any API response. The account can hold balances across multiple assets. Each (account_commitment, asset_id) pair has an independent AccountRecord.

​
Request body

{
  "account_commitment": "abc123...",
  "wallet_proof": "<base64-encoded ECDSA signature>"
}
FieldTypeRequiredDescription
account_commitmentstringyesH(wallet_address) using SHA-256
wallet_proofbytesyesECDSA signature proving ownership of the wallet

​
Deriving the account commitment

// JavaScript (browser / Node.js)
const walletAddress = "0xabc...";
const commitment = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(walletAddress)
);
const commitmentHex = Array.from(new Uint8Array(commitment))
  .map(b => b.toString(16).padStart(2, "0"))
  .join("");

# Shell
COMMITMENT=$(echo -n "0xabc..." | sha256sum | awk '{print $1}')

​
Signing the wallet proof

The wallet_proof is an ECDSA signature over the canonical registration message: 
SHA-256("shyware:register:" + account_commitment)
Sign this with the wallet’s private key and encode the result as base64.

​
Response

{
  "account_commitment": "abc123...",
  "height": 12
}

​
Errors

StatusErrorCause
400missing account_commitmentRequired field absent
400missing wallet_proofRequired field absent
400invalid wallet_proofSignature does not verify against commitment
409account already registeredCommitment already exists on-chain

​
Account balances (admin only)

Account balances are not publicly queryable. The operator can query balances via the admin API using the account commitment: 
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  https://your-node/api/v1/admin/accounts/abc123.../balance/usdc

{
  "account_commitment": "abc123...",
  "asset_id": "usdc",
  "balance": 900000,
  "updated_at": 1741651200,
  "height": 142
}
This endpoint is intentionally restricted. Balance information is operator-only and is accessible to authorities under legal process (subpoena / MLAT).