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.
Your own wallet
Open the app on the Wallet tab. No account, owner key or agent installation is required.
- 1Choose how to openCreate 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.
- 2Add fundsSend 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.
- 3ShieldChoose 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%.
- 4Swap or payReview and confirm a supported swap quote, or use Pocket Pay with a recipient's Pocket receiving address. Proofs are generated in your browser.
- 5Return whenever you needUnlock 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.
- 1Create an allocationChoose 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.
- 2Fund itSend 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.
- 3Activate the funded budgetRecover funds and activate the allocation. Later incoming funds do not silently increase an active budget.
- 4Manage here, connect your AIUse 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.
- 5Take your funds backOpen 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.
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.
| Action | Who | What and how much | Which notes |
|---|---|---|---|
| Deposit | Public | Public | creates one note, contents encrypted |
| Holding | Private | Private | Private |
| Swap quote | quote service / RPC | quote service / RPC | not sent |
| Swap settlement | Public | Public | Private |
| Pocket Pay | public sender, private recipient | Private | Private |
| Withdraw | Public | Public | Private |
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.
Pocket for agents
Pocket supports two agent access modes. Both use service-enforced permissions, and the wallet service and its host are trusted.
| Mode | Access | Connection |
|---|---|---|
| Blind allocation | Allowed 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 wallet | Exact 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.
- 1Connect ChatGPT or ClaudeAdd 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.
- 2Or use another MCP clientOpen 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.
- 3Give it the skillOptional. 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.
- 4Ask for a tradeYour agent reads its choices, asks for something like "buy BNB with 5%", and the exact trade waits in Approvals for you.
| Blind tool | Does |
|---|---|
pocket_blind_capabilities | Reads token/recipient access, percentage choices, positions, funding permission and execution mode. |
pocket_blind_propose | Proposes a percentage trade or alias payment. Exact values stay in the owner interface. |
pocket_blind_shield | Prepares the owner-defined initial private BNB budget, retains gas and enables the wallet; requires an explicit automatic funding grant. |
pocket_blind_execute | Executes a ready trade or payment under an automatic mandate. Ask-each-time connections use owner approval. |
pocket_blind_status | Reads a coarse status for a request. |
pocket_blind_cancel | Cancels a request that was not sent yet. |
pocket_blind_pause | Pauses its own connection. Only you can resume it. |
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.
| Tool | Does | Spends budget |
|---|---|---|
pocket_balance / pocket_recover | Reads cached balances or recovers notes from events. | No |
pocket_create_wallet | Creates the wallet assigned to this credential. | No |
pocket_quote | Requests a quote from the routes configured for the wallet service. | No |
pocket_shield / pocket_trade | Shields BNB or proves and settles a swap. | Yes |
pocket_withdraw | Exits funds to the wallet’s public address. | Yes |
pocket_usage / pocket_operation | Reads budget use or an operation’s persisted status. | No |
pocket_receive_address / pocket_pay | Shares 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.
- 1Active and unexpiredA revoked or expired credential cannot authorize operations. Revocation is permanent.
- 2Allowed action and tokensShielding, quoting, trading, payments and withdrawals are enabled separately. Both trade assets must be allowed.
- 3Allowed recipientAn optional Pocket Pay allowlist restricts payments to exact receiving addresses.
- 4Slippage within capThe requested trade slippage must fit the configured basis-point limit.
- 5Within token budgetsEach asset has a per-action cap and a day, week or lifetime budget, measured in exact token amounts.
- 6Within gas budgetA separate BNB allowance limits total gas and the maximum cost of one transaction.
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.
| Mode | How it works | Worst case if the agent is compromised |
|---|---|---|
| Scoped credential | The service signs only operations allowed by that credential’s policy. | It can spend within that credential’s configured limits. |
| Separate wallet | Its own wallet balance adds a limit on available funds. | It can spend available funds within its credential’s limits. |
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.
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.
- chainIdthe chain ID, so a note can't move to another chain
- poolthis pool's address
- ownerthe wallet that deposited
- assettoken address, zero for native BNB
- amountvalue after the fee
- spendKeyHashPoseidon hash of your spend secret
- rhorandom, feeds the nullifier
- blindingrandom, hides everything else
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.
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.
| Key | What it does | If someone else gets it |
|---|---|---|
| Viewing key | Decrypts your notes so you can see balances and recover them from chain events. | They can see your balances. They cannot spend. |
| Spending key | Derives 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.
| Circuit | Public inputs | Binds |
|---|---|---|
| Deposit | 6 | chain, pool, depositor, asset, net amount, commitment |
| Trade | 18 | chain, pool, up to 2 roots and nullifiers, pair, amounts, deadline, executor, up to 2 outputs, output ciphertext hash |
| Withdrawal | 15 | chain, pool, up to 2 roots and nullifiers, owner, asset, amount, deadline, change commitment, change ciphertext hash |
| Transfer (Pocket Pay) | 13 | chain, 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.
Shield
Shielding moves tokens from your wallet into the pool and gives you a private note.
- 1Create and seal the noteYour browser picks fresh randomness, derives a spend secret and encrypts the note to your viewing key.
- 2Prove the depositThe proof binds the chain, pool, your address, the asset, the net amount and the commitment.
- 3Get an admissionYou 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.
- 4SubmitThe pool checks the proof, consumes the approval, and for tokens confirms that exactly the stated amount arrived. Then the note is inserted.
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.
- 1Get a quotePocket checks supported PancakeSwap V2/V3 and Four/Flap routes, then returns a signed quote within your slippage limit. Quotes expire after two minutes.
- 2Prove the tradeYour browser proves you own one or two notes covering the sell amount and describes up to two outputs: the bought asset and your change.
- 3Settle atomicallyThe 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 RFQ | Message | Visible to relays |
|---|---|---|
| 28631 | Request | pair, amount, deadline |
| 28632 | Quote | encrypted |
| 28633 | Execute | encrypted |
| 28634 | Result | encrypted |
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.
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.
| Action | Charged on | Example |
|---|---|---|
| Shield | the deposit | 10 BNB in → 9.95 BNB note, 0.05 fee |
| Swap | the bought amount | quote of 600 USDT → 597 USDT note, 3 fee |
| Withdraw | nothing | free, you only pay gas |
| Pocket Pay | nothing | free, 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.
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.
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.
| Authority | Current powers |
|---|---|
| Governance | Pause deposits, trades and Pocket Pay; block tokens for deposits/trades; change deposit admission configuration; authorize implementation upgrades. |
| Treasury | Claim recorded protocol-fee reserves through the current fee-claim function. |
| Hosted operator | Hold 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
| Limit | Value |
|---|---|
| Notes spent per action | 1 or 2 |
| Swap outputs | 1 or 2 (bought asset plus change) |
| Withdrawal change | 0 or 1 note |
| Largest amount | below 2¹²⁸ base units |
| Pocket Pay notes | 1 or 2 in, 1 or 2 out |
| Admission lifetime | Shared service: 120 seconds; contract maximum: 300 seconds |
| Quote lifetime | Shared swap quotes: up to 120 seconds; cached full-wallet quotes: at most 60 seconds. Use the displayed expiry. |
| Chain | BNB Smart Chain |
| Tokens | BNB and compatible BSC token contracts; swapping also needs a supported route and liquidity. |
FAQ
Glossary
| Term | Meaning |
|---|---|
| Note | A private record of value you own inside the pool. |
| Commitment | The Poseidon hash of a note. The only thing stored in the tree. |
| Nullifier | A one-time tag revealed when a note is spent, to stop double spends. |
| Root | The top hash of the note tree. Proofs show membership under a known root. |
| Viewing key | Decrypts your notes. Read-only. |
| Spending key | Lets you spend notes. Keep it secret. |
| Admission | A short-lived authorization automatically issued for one signed deposit request. |
| Solver | A quoting service. Pocket's shared service signs quotes for supported PancakeSwap V2/V3 and Four/Flap routes. |
| Executor | The contract that receives the sell side and must return the exact buy side. |
| Access key | A scoped credential that lets one agent use one wallet, only within its policy. |
| Owner service | The hosted or self-operated service that holds managed wallet keys and enforces agent policies. |
| Receiving address | What you share to get paid with Pocket Pay. It never reveals your spending key. |
| Epoch | A full 32-level tree, sealed so a new one can start. |