Documentation

How Pocket works

Getting started

What is Pocket

Pocket is a private wallet, trading and payment layer for people and AI agents on BNB Smart Chain.

The pool contract holds custody and checks Groth16 proofs of valid note transitions. Spending proofs hide which notes are consumed. Direct transaction senders, deposits, trading amounts and withdrawals remain visible on-chain.

network
BNB Smart Chain
fee
0.5%
proofs
Groth16
examples

Your own wallet

Open the app on the Wallet tab. No account, owner key or agent installation is required.

  1. 1
    Choose how to open
    Create a wallet makes a complete Pocket wallet in your browser: choose a passphrase and download its encrypted backup. No extension is needed. Use an existing wallet opens your connected extension wallet with a signature.
  2. 2
    Add funds
    Send BNB or compatible tokens on BNB Smart Chain to the funding address shown in your wallet. Keep a little public BNB there for transaction fees. Public funds are separate from your private balance.
  3. 3
    Shield
    Choose BNB or a compatible token and an amount. Pocket creates the proof in your browser. A wallet extension asks you to sign; a passphrase wallet signs locally. The deposit fee is 0.5%.
  4. 4
    Swap or pay
    Review and confirm a supported swap quote, or use Pocket Pay with a recipient's Pocket receiving address. Proofs are generated in your browser.
  5. 5
    Return whenever you need
    Unlock your saved backup, import the file on another device, or reopen with the same extension signature. Keep the backup and passphrase: a passphrase alone cannot recreate lost keys. Withdrawals return to your public funding wallet.

Your agent workspace

The Agents tab is a separate hosted workspace. Sign in with a public wallet message to return to your saved allocations, approvals and activity.

  1. 1
    Create an allocation
    Choose a spending budget, gas limit, slippage and expiry. New connections can act automatically with any supported token and any Pocket recipient; ask-each-time mode is optional. The allocation has its own service-managed wallet; your login wallet is only your account identity.
  2. 2
    Fund it
    Send public BNB to the displayed allocation wallet and keep some for gas. Shield BNB, then use the owner conversion action if your budget is in another token. You can also send it a Pocket Pay note using its receiving address.
  3. 3
    Activate the funded budget
    Recover funds and activate the allocation. Later incoming funds do not silently increase an active budget.
  4. 4
    Manage here, connect your AI
    Use Pocket to see balances, review approvals, set limits and track activity. Connect your AI app through MCP or the SDK for instructions and trading. Talk to agent inside Pocket is coming soon.
  5. 5
    Take your funds back
    Open your agent and choose Return funds. Review the tokens, your signed-in receiving wallet and the maximum network fees, then confirm. Trading pauses while Pocket returns private funds, public tokens and unused BNB. Progress and receipts stay available if you close the page. Exporting a key is not required.
Hosted wallet custody
Pocket's backend holds the allocation wallet keys and enforces its permissions. Creating an allocation does not launch an AI model. Your personal browser wallet keeps its own note keys locally.

What is private

Notes keep their contents encrypted. Browser wallets and hosted agent wallets submit transactions directly, so the public sender and timing remain visible. Browser note keys stay in the browser; the hosted service holds and can read its managed wallets.

ActionWhoWhat and how muchWhich notes
DepositPublicPubliccreates one note, contents encrypted
HoldingPrivatePrivatePrivate
Swap quotequote service / RPCquote service / RPCnot sent
Swap settlementPublicPublicPrivate
Pocket Paypublic sender, private recipientPrivatePrivate
WithdrawPublicPublicPrivate

On a swap, the sender, pair, amounts, executor, nullifiers and timing are public. Pocket Pay publishes commitments, nullifiers and encrypted receipts without a public token payout. It does not hide the transaction sender.

Agents

Pocket for agents

Pocket supports two agent access modes. Both use service-enforced permissions, and the wallet service and its host are trusted.

ModeAccessConnection
Blind allocationAllowed choices and percentage requests. Exact balances, resolved amounts and receipts stay in the owner's workspace. No agent withdrawals.Hosted SDK, remote MCP or restricted stdio connector.
Full walletExact balances, recovery, quotes and permitted shielding, trading, payments and own-wallet withdrawals.Owner-operated wallet service, JavaScript SDK and local stdio MCP.

Use Blind mode when an external agent should propose actions without receiving exact financial details. Use full wallet tools only when that agent is meant to see those values.

Connecting an agent

Create an agent in Pocket: choose its name, look and preferred AI app, then review its starter limits. Its wallet is saved in your workspace. Add funds and enable trading when ready. The AI runs in the app you connect; Pocket provides its wallet, permissions and activity history.

Connect over MCP

In Blind mode your agent reaches Pocket through a remote MCP server. There is nothing to install on your side, and the agent does not receive exact balances or amounts through those tools. Keep it separate from your owner browser, files and screens.

  1. 1
    Connect ChatGPT or Claude
    Add Pocket in your AI app using https://www.bnbpocket.com/api/pocket/mcp. Choose OAuth, sign into Pocket, select your agent wallet and review its execution permissions. Automatic BNB wallets can connect before funding. You do not need to export a key or install software for this path.
  2. 2
    Or use another MCP client
    Open the wallet's Connections tab and create a scoped access key. Claude Code has a one-line setup command; Cursor has a settings file. Other clients use Streamable HTTP with the Pocket URL and bearer key. Keep the key in the client's credential settings, never in a chat message.
  3. 3
    Give it the skill
    Optional. Open Read instructions in Connections, then copy them into your agent. A plain Markdown file is also available for skill importers. The instructions explain percentages, approvals and retries, and contain no keys.
  4. 4
    Ask for a trade
    Your agent reads its choices, asks for something like "buy BNB with 5%", and the exact trade waits in Approvals for you.
Blind toolDoes
pocket_blind_capabilitiesReads token/recipient access, percentage choices, positions, funding permission and execution mode.
pocket_blind_proposeProposes a percentage trade or alias payment. Exact values stay in the owner interface.
pocket_blind_shieldPrepares the owner-defined initial private BNB budget, retains gas and enables the wallet; requires an explicit automatic funding grant.
pocket_blind_executeExecutes a ready trade or payment under an automatic mandate. Ask-each-time connections use owner approval.
pocket_blind_statusReads a coarse status for a request.
pocket_blind_cancelCancels a request that was not sent yet.
pocket_blind_pausePauses its own connection. Only you can resume it.
Which apps work
ChatGPT and Claude web use the verified OAuth sign-in path. Other MCP clients can use a scoped bearer key, or OAuth with an approved callback URL. The public MCP address is https://www.bnbpocket.com/api/pocket/mcp. Revoking a connection denies its next request.

Full wallet tools

These exact-value tools use the owner-operated service and local stdio MCP. They are not exposed by the hosted Blind MCP endpoint.

ToolDoesSpends budget
pocket_balance / pocket_recoverReads cached balances or recovers notes from events.No
pocket_create_walletCreates the wallet assigned to this credential.No
pocket_quoteRequests a quote from the routes configured for the wallet service.No
pocket_shield / pocket_tradeShields BNB or proves and settles a swap.Yes
pocket_withdrawExits funds to the wallet’s public address.Yes
pocket_usage / pocket_operationReads budget use or an operation’s persisted status.No
pocket_receive_address / pocket_payShares a receiving address or sends a shielded payment.Payment only

Permissions

Blind connections share wallet-wide spending and gas limits; selling does not refill spending. New open connections can trade any supported token and pay any valid Pocket recipient automatically within an explicit mandate. Ask-each-time mode remains available. Existing grants retain their original authority. Full wallet credentials use the separate policy below, including pending reservations.

  1. 1
    Active and unexpired
    A revoked or expired credential cannot authorize operations. Revocation is permanent.
  2. 2
    Allowed action and tokens
    Shielding, quoting, trading, payments and withdrawals are enabled separately. Both trade assets must be allowed.
  3. 3
    Allowed recipient
    An optional Pocket Pay allowlist restricts payments to exact receiving addresses.
  4. 4
    Slippage within cap
    The requested trade slippage must fit the configured basis-point limit.
  5. 5
    Within token budgets
    Each asset has a per-action cap and a day, week or lifetime budget, measured in exact token amounts.
  6. 6
    Within gas budget
    A separate BNB allowance limits total gas and the maximum cost of one transaction.
Start small
Give a new agent a small token budget, only the actions it needs, and an expiry. Policy edits invalidate previous quotes.

Where rules are enforced

Pocket keeps wallet keys in the owner service’s encrypted vault and gives agents scoped credentials. These are service-enforced permissions; the operator and host remain trusted. An owner can create separate wallets or assign credentials to an existing wallet.

ModeHow it worksWorst case if the agent is compromised
Scoped credentialThe service signs only operations allowed by that credential’s policy.It can spend within that credential’s configured limits.
Separate walletIts own wallet balance adds a limit on available funds.It can spend available funds within its credential’s limits.
Funding and gas
A wallet can receive private notes through Pocket Pay or shield a public BNB deposit. It still needs public BNB to pay gas. Revocation stops new authorizations; it cannot recall an already submitted transaction.

Pocket Pay

Pocket Pay sends a recipient-owned note within the pool. Share the receiving address from the app, paste it into Pocket Pay, choose a token and amount, and submit. The recipient recovers the note from encrypted events and can pay onward, trade or withdraw.

A separate transfer circuit checks ownership, membership and conservation. A payment consumes up to two notes and produces a recipient note plus optional sender change. It moves no public assets and charges no additional protocol fee. Amount, asset and recipient remain private inputs; the transaction sender and timing remain public. Receiving addresses belong to one chain and pool.

Market watchers

In an allocation's Watchers tab, choose a supported asset, review a reference DEX quote, and set an above/below percentage threshold, trade size and expiry.

A watcher samples the configured market route. When its threshold is reached, it creates one proposal in Approvals. It does not execute automatically or send a messenger notification. The owner must review a fresh exact quote before trading.

Expired, paused, revoked or stopped watchers cannot trigger new work. A DEX quote is a route-specific observation, not an independent price oracle or a guaranteed fill.

Recipient aliases

A saved alias is an optional shortcut for a Pocket receiving address; open connections can supply a valid receiving address directly. The alias belongs to that allocation; an external agent sees its label and reference, not the mapped address.

A command such as pay 5% to supplier uses the initial budget asset and an allowed buy-percentage choice. Payments share the buy-turnover, token and gas limits. Open automatic connections execute payments within their granted limits. Approval-mode connections require owner review.

Removing an alias invalidates unsubmitted requests. It cannot recall a released transaction. The personal Wallet tab uses full receiving addresses directly.

Concepts

Notes

A note is a private record that says "this owner has this much of this asset in this pool". Your balance is the sum of your unspent notes. Notes are never edited: spending one burns it and creates new ones.

The pool stores only a commitment, a Poseidon hash of all the note's fields. Two random values, rho and blinding, make every commitment unique and unguessable even for identical amounts.

  • chainId
    the chain ID, so a note can't move to another chain
  • pool
    this pool's address
  • owner
    the wallet that deposited
  • asset
    token address, zero for native BNB
  • amount
    value after the fee
  • spendKeyHash
    Poseidon hash of your spend secret
  • rho
    random, feeds the nullifier
  • blinding
    random, hides everything else
Poseidon→
commitment
0x1f3a9c0e77b2d45a8e60c1f4b93d2e7a05c6b8f1
The only thing stored in the tree. It reveals nothing on its own.

Alongside the commitment, the pool emits the note encrypted to your viewing key: a 401-byte ciphertext sealed with HPKE (X25519, HKDF-SHA256, ChaCha20-Poly1305). Anyone can see it. Only holders of the matching viewing key can open it; this includes the operator for hosted wallets.

The note tree

Every new commitment becomes a leaf in a Poseidon Merkle tree with 32 levels, room for about 4.3 billion notes. Each insert produces a new root.

To spend, you prove your note is a leaf under some root the pool has recorded, without saying which leaf. Pocket keeps every root for the life of the pool, so notes created at different times can be spent together, each with its own membership path.

When a tree fills up
After 232 leaves the tree is sealed into an epoch and a fresh one starts. Old roots stay valid.

Nullifiers

When you spend a note you reveal its nullifier, a Poseidon hash of the chain, pool, the note's rho and your spend secret. The pool marks it as burned. Trying to spend the same note again reveals the same nullifier and is rejected with InvalidSpend.

The nullifier does not directly reveal its note commitment. The proof shows that some note was spent; public timing and transaction patterns can still support inferences.

Keys

The personal wallet generates two independent note keys in your browser. Hosted allocation keys are generated and stored by the wallet service.

KeyWhat it doesIf someone else gets it
Viewing keyDecrypts your notes so you can see balances and recover them from chain events.They can see your balances. They cannot spend.
Spending keyDerives a spend secret per note. Needed to create nullifiers and prove ownership.It supplies spending authority when combined with the required note data. Guard it.

The two are generated separately on purpose, and backups refuse to export them if they are identical. A new Pocket wallet also creates its own transaction key. An extension wallet keeps its existing signer. Deposits bind the funding wallet as note owner, and withdrawals pay it.

Proofs

Each action has its own Groth16 circuit on the BN254 curve, written as readable Circom sources in Pocket v2. Your wallet software, the browser or the owner service, generates the proof, and a verifier contract checks it on-chain. What a proof binds is listed below. Change any of it after proving, and verification fails.

CircuitPublic inputsBinds
Deposit6chain, pool, depositor, asset, net amount, commitment
Trade18chain, pool, up to 2 roots and nullifiers, pair, amounts, deadline, executor, up to 2 outputs, output ciphertext hash
Withdrawal15chain, pool, up to 2 roots and nullifiers, owner, asset, amount, deadline, change commitment, change ciphertext hash
Transfer (Pocket Pay)13chain, pool, up to 2 roots and nullifiers, deadline, up to 2 output commitments, output ciphertext hash. No asset or amount.

Binding the chain and pool means a proof can't be replayed anywhere else. Trade, withdrawal and payment proofs also bind output ciphertext hashes. Deposits bind their ciphertext through the signed admission.

Using Pocket

Shield

Shielding moves tokens from your wallet into the pool and gives you a private note.

  1. 1
    Create and seal the note
    Your browser picks fresh randomness, derives a spend secret and encrypts the note to your viewing key.
  2. 2
    Prove the deposit
    The proof binds the chain, pool, your address, the asset, the net amount and the commitment.
  3. 3
    Get an admission
    You sign the deposit request. Pocket automatically checks the signature and exact deposit details, then returns an approval valid for 2 minutes. No operator approval step is needed.
  4. 4
    Submit
    The pool checks the proof, consumes the approval, and for tokens confirms that exactly the stated amount arrived. Then the note is inserted.
Fee-on-transfer tokens
If a token delivers less than it claims, the deposit reverts with TransferMismatch. Compatible BSC token contracts are eligible by default. Add a token by its contract address; no listing request is needed.

Swap

Swaps happen inside the pool. You spend notes in one asset and receive a note in another, without revealing which notes were spent. The pair, the amounts and the sending wallet are public.

  1. 1
    Get a quote
    Pocket checks supported PancakeSwap V2/V3 and Four/Flap routes, then returns a signed quote within your slippage limit. Quotes expire after two minutes.
  2. 2
    Prove the trade
    Your browser proves you own one or two notes covering the sell amount and describes up to two outputs: the bought asset and your change.
  3. 3
    Settle atomically
    The pool sends the sell amount to the quoted Pocket executor, which must return exactly the quoted buy amount. If reserves moved or anything else is off, the whole trade reverts, nullifiers included.
Optional solver RFQMessageVisible to relays
28631Requestpair, amount, deadline
28632Quoteencrypted
28633Executeencrypted
28634Resultencrypted

Withdraw

Withdrawing spends one or two of your notes and sends tokens to the note owner, the wallet assigned when the note was deposited or received through Pocket Pay. If the notes are worth more than you take out, the rest comes back as one change note.

  • No fee on withdrawals.
  • The current implementation allows withdrawals while paused or after a token is disabled. Keys, gas, chain access and a functioning token transfer are still required.
  • The proof reveals the owner, asset and amount, but not which notes were spent.
Paying someone else?
Withdrawals always go back to the note owner. To send value to another agent, user or service privately, use Pocket Pay: the recipient gets a note only they can spend.

Fees

One flat protocol fee of 50 basis points, rounded down: the fee on an amount is that amount divided by 200, ignoring the remainder.

ActionCharged onExample
Shieldthe deposit10 BNB in → 9.95 BNB note, 0.05 fee
Swapthe bought amountquote of 600 USDT → 597 USDT note, 3 fee
Withdrawnothingfree, you only pay gas
Pocket Paynothingfree, you only pay gas

The current implementation tracks note liabilities separately from each asset’s fee reserve and checks exact balance changes during settlement. Its fee-claim function pays only the recorded reserve to the treasury. Governance upgrade authority is explained below.

Deposit admission

Pocket automatically authorizes correctly signed deposit requests from any wallet. This short-lived authorization is tied to one exact deposit. Admission only ever applies to deposits. Trades, withdrawals and Pocket Pay on existing notes don't need it.

  • You sign the request with the depositing wallet, so nobody can request admission on your behalf.
  • The shared service issues 2-minute approvals, within the contract’s 5-minute maximum. They are tied to the pool, your address, the asset, the amounts, the commitment and the ciphertext hash.
  • Each approval works once. Replays revert with InvalidAdmission.
  • An invalid request only blocks that deposit. It never touches existing notes or withdrawals.

If admission is unavailable, new deposits wait; existing notes can still be withdrawn. This automatic signature check is not a sanctions-screening claim. Governance can change the admission signer or policy without redeploying the pool.

Backup and recovery

Personal browser wallet

Download the encrypted backup during creation or with the Backup button. New standalone wallet backups contain the transaction key and both private-note roots, encrypted with AES-256-GCM and PBKDF2-SHA256 using 600,000 iterations. Your browser can remember this locked file; it does not store the passphrase in plain text. Save another copy outside the browser.

On another device, choose I have a backup, import the file and unlock it. Pocket restores the same funding address and reads encrypted chain events to recover notes and Pocket Pay receipts. No extension is required for a standalone wallet. Older note-only backups and backups made from an extension wallet still use the original public wallet to sign transactions.

Use an existing wallet opens your extension's private profile with a signature. You can also save an encrypted note backup from that screen. Keep it in case your extension changes how it signs messages.

A passphrase alone is not a recovery phrase
The passphrase unlocks the random keys in your file; it does not recreate them. Losing every copy of the backup means losing those keys. A chain rescan still needs the keys.

Hosted allocations

Sign in with the same account wallet to return to your allocation. Recovery depends on Pocket's encrypted service vault and separately protected master key. A personal browser backup cannot restore a hosted allocation. Restoring a service backup preserves wallet history but revokes external connections and pauses allocations for review.

Security

Checks and evidence

Recorded fork scenarios exercise invalid proofs, double spends, cross-chain and cross-pool replay, altered ciphertexts, stale quotes, expired or reused admissions, transfer mismatches and settlement shortfalls. Each report records its tested source version.

Explore the recorded fork checks. The interactive console illustrates test cases; it does not submit live attacks. Marked receipts were mined on a local BSC fork. Passing these scenarios does not prove correctness under every condition or constitute an independent review.

Governance and trust

Pocket's mainnet pool is an upgradeable UUPS proxy. The deployer wallet also controls governance and receives protocol fees.

AuthorityCurrent powers
GovernancePause deposits, trades and Pocket Pay; block tokens for deposits/trades; change deposit admission configuration; authorize implementation upgrades.
TreasuryClaim recorded protocol-fee reserves through the current fee-claim function.
Hosted operatorHold allocation wallet keys and enforce hosted-agent permissions. Personal browser note keys remain local.

The current implementation has no administrative function to transfer private note balances, and its pause flag does not block withdrawals. An upgrade can change custody behavior, so those are current-code properties, not permanent limits on governance.

Limits

LimitValue
Notes spent per action1 or 2
Swap outputs1 or 2 (bought asset plus change)
Withdrawal change0 or 1 note
Largest amountbelow 2¹²⁸ base units
Pocket Pay notes1 or 2 in, 1 or 2 out
Admission lifetimeShared service: 120 seconds; contract maximum: 300 seconds
Quote lifetimeShared swap quotes: up to 120 seconds; cached full-wallet quotes: at most 60 seconds. Use the displayed expiry.
ChainBNB Smart Chain
TokensBNB and compatible BSC token contracts; swapping also needs a supported route and liquidity.
Reference

FAQ

The current pool requires valid proofs for note spending, but governance can upgrade its implementation. Personal note keys stay in your browser; hosted allocation keys are held by the service operator. Both governance and hosted custody are trust assumptions.

Glossary

TermMeaning
NoteA private record of value you own inside the pool.
CommitmentThe Poseidon hash of a note. The only thing stored in the tree.
NullifierA one-time tag revealed when a note is spent, to stop double spends.
RootThe top hash of the note tree. Proofs show membership under a known root.
Viewing keyDecrypts your notes. Read-only.
Spending keyLets you spend notes. Keep it secret.
AdmissionA short-lived authorization automatically issued for one signed deposit request.
SolverA quoting service. Pocket's shared service signs quotes for supported PancakeSwap V2/V3 and Four/Flap routes.
ExecutorThe contract that receives the sell side and must return the exact buy side.
Access keyA scoped credential that lets one agent use one wallet, only within its policy.
Owner serviceThe hosted or self-operated service that holds managed wallet keys and enforces agent policies.
Receiving addressWhat you share to get paid with Pocket Pay. It never reveals your spending key.
EpochA full 32-level tree, sealed so a new one can start.