Server API

Surety is a custodial USDC service. Its operator holds the service wallet keys. Solana records deposits and withdrawals; Surety’s database records balances, pool shares, agents, guarantees, loans and scores. No Surety program is deployed or required for these operations.

Money flow

1. Sign in by signing an expiring wallet challenge. This proves wallet ownership without transferring funds.
2. On the Account page, approve an exact USDC transfer to the service vault. The server credits it only after a successful canonical Solana receipt.
3. Use your account balance to lend, stake as a guarantor, post a seat bond or repay a loan. Borrowing credits the operator’s Surety account.
4. Withdrawing pool shares or stake returns value to your account balance. Request a separate withdrawal to your connected wallet.

Credit and losses

Loans are 5–500 USDC for 1–30 days. The base fee is 1% per 30 days, rounded up to a USDC base unit. A guarantor may add a premium within the agent owner’s consent. Base fees split 50% to lenders, 25% to the guarantor and the remainder to the reserve. Premiums go to the guarantor. The guarantor’s locked shares absorb defaults first; insufficient backing can still cause lender losses.

An exit within seven days of adding funds costs 0.5%. Seat bonds follow the guarantor’s displayed terms. Three loans held for at least seven days and repaid after taking the seat qualify for bond release. Cancelling an unused seat retains 10% of its bond for the guarantor. A default forfeits the seat bond.

Control and recovery

The service operator can affect availability and controls the custody key and database. A database record is not a permissionless on-chain claim. Signed withdrawals are journaled before broadcast; retries reuse the same transaction. Confirmed deposits are credited once. If a recorded receipt changes canonical block, payouts pause for reconciliation. Server outages, compromised keys and accounting failures remain custody risks.

Authentication and operations

Base URL: https://surety.cash/api/backend. POST /auth/challenge with {wallet}; sign the returned UTF-8 message with the wallet’s Ed25519 key, then POST /auth/login with {id, signature} (signature in base64). Use the returned token as a Bearer token for 30 minutes. Never send a private key.

POST /command accepts {id, action, args}. Use a UUID as the idempotency key and reuse it only for an identical request. Amounts are integer USDC base units (1 USDC = 1,000,000). Supported actions: registerAgent, createAgent, updateAgent, consent, revokeConsent, leave, openSponsor, addStake, unstake, claimFees, vouch, releaseLine, freezeLine, setSeatTerms, takeSeat, releaseBond, forfeitBond, deposit (lend account funds), withdraw (redeem pool shares), borrow, repay, repayAll, markDefault.

GET /account returns the authenticated account balance and transfer history. POST /deposit/prepare with {id, amount}, sign the returned transaction without changes, then POST /deposit/submit with {id, raw} (raw in base64). POST /withdraw with {id, amount} reserves a payout to the authenticated wallet. Poll /account for a confirmed receipt; a queued request or broadcast is not a successful transfer.

The previous Anchor SDK and MCP instruction transport target the smart-contract version and must not be used against this server ledger. Agents can use this authenticated HTTP API directly.