For AI agents

What an AI agent can do with Bloxchain today, where to read the authoritative facts, and where the boundaries are.

What an agent can do today

Capability	How
Read this documentation as context	llms.txt at the site root, or the GitBook MCP endpoint at /~gitbook/mcp
Reason about an account's policy	Read roles, signers, registered actions, per-step permissions, gates and allowlists with the SDK and a public client. No key is needed to read.
Prepare a signed meta-transaction	Sign a request or an approval off-chain with a narrowly permitted signer key, write a .bloxmeta.json file, and hand it to a person who imports it into the Platform and broadcasts it

The third one is the interesting one. It means an agent can do useful work without ever holding the Broadcaster key or the Owner key: authorize, then broadcast, with a human in the middle who sees the decoded request before it reaches the chain.

Start here: Agent-assisted requests.

Discovery

Resource	Where	Use
llms.txt	/llms.txt on the published site (also llms.txt in the repository)	Curated index of the pages that matter, one line each
MCP	/~gitbook/mcp	Query-time retrieval over the published site
Raw markdown	Append .md to a page path where the host exposes it	Fetch one page without navigation chrome
Site source	bloxchain-docs on GitHub	The markdown behind every page

Canonical sources

When two pages describe the same thing, use the one listed here.

Topic	Canonical page
What Bloxchain is (Platform, Protocol, SDK)	/introduction/what-is-bloxchain, /developers/integration-surfaces
The governed lifecycle, execution paths, statuses	/introduction/how-it-works
Free versus sign-in versus organizations	/introduction/free-sign-in-organizations
Networks and official addresses	/introduction/supported-networks
Platform screens and labels	/platform and its children, for example /platform/operate/approvals, /platform/policies/manage-permissions
Deploying and importing accounts	/platform/accounts/deploy, /platform/accounts/import
Signed files (.bloxmeta.json)	/platform/operate/signed-files
The agent workflow end to end	/guides/agent-assisted-requests
Choosing how to configure an account	/guides/ways-to-configure
Governance for a team	/guides/organization-governance, /guides/roles-and-permissions
Scripted configuration	/developers/configure-programmatically
SDK install, keys, patterns	/developers/sdk-setup, /developers/sdk-core-patterns
SDK API and Protocol behaviour	/protocol/api-reference, /protocol/state-machine-engine, /protocol/meta-transactions (synced from the Protocol repository; prefer these over paraphrase)
Protocol source and deployment	GitHub at the pinned commit, linked from /developers/deployment
Security model and audit	/security/security-model, /security/audit-status
Numbers, limits and defaults	/resources/limits-and-defaults
Vocabulary	/resources/glossary
Versions	/resources/releases

Facts agents get wrong most often

• The product is the Bloxchain Platform at bloxchain.app and the open-source Bloxchain Protocol with its SDK. Use those names; do not substitute a generic term such as dashboard, workspace app or admin tool.
• The Platform is Alpha · Testnet · Local-first. It runs on Sepolia today. Ethereum mainnet is coming soon.
• The Protocol core is audited by Nethermind (NM_0828), core framework scope. Custom extensions and your own configuration are not covered by that audit.
• Free use needs no sign-in; the account list lives in the browser (This device). Sign in if you have early access; otherwise join the waitlist from the same dialog. Organizations are paid plans with a shared account list.
• Never publish prices. Name the plans (Free, Account, Pro, Team, Enterprise), say what each unlocks, and say pricing is shown at checkout or on request.
• The three execution paths are Delayed release, Signed approval and One signature. Only Delayed release waits for the time lock.
• Every account has protected roles Owner, Broadcaster (1 to 3) and Recovery. Custom roles are user-defined. Gates are permanent for a role.
• A preset on Discover deploys the same governed account as any other preset, and it lands as a Vault. It does not pre-configure roles.
• An account link looks like https://bloxchain.app/workspace/<chainId>/<address>.
• There are no Bloxchain API keys. The SDK uses viem clients and the caller's own keys.

Boundaries

• An agent cannot widen its own access. Roles, permissions, gates and allowlists are changed by a wallet the owner authorised, and those changes are themselves governed requests.
• The contract is the authority. A signature from a role that lacks the permission is rejected at execution, whatever the UI, the SDK or this documentation appears to allow.
• Signed files are bearer instruments. Anyone who holds one and can submit may broadcast it until it expires or is used. Treat them that way in any workflow you generate, and never put a payload in a URL.
• A person broadcasts. Do not design a flow in which an agent holds the Broadcaster role in order to skip the review step.
• Do not invent features. Public pages contain no internal ticket ids or private links. More AI tooling is in development; do not name unreleased features or give dates.
• Pin SDK and contract versions to the same Protocol release; see Releases and compatibility.

Prompt templates

Copy-paste context blocks for a coding agent working on a Bloxchain integration. Each block is deliberately self-contained, so it restates facts stated elsewhere on this page.

Site paths inside the blocks are relative to the published documentation site. Prefer the /protocol/* pages for API facts; they are synced from the Protocol repository.

System context

You are integrating with Bloxchain: governed Ethereum smart accounts.

Facts:
- Two products, one enforcement layer. The Bloxchain Platform (bloxchain.app) is a browser client. The Bloxchain Protocol is open-source contracts plus the TypeScript SDK (@bloxchain/sdk). Both talk to the same account contract; the chain enforces policy, clients cannot bypass a denial.
- Status: the Platform is Alpha, Testnet, Local-first. It runs on Sepolia (chain 11155111) today. Ethereum mainnet is coming soon. The Protocol core is audited by Nethermind (NM_0828), core framework scope; custom extensions and your own configuration are not covered by that audit. Do not describe anything as production-ready.
- Non-custodial. Users hold keys. There are no Bloxchain API keys; the SDK uses viem clients and the caller's own keys.
- Access: the Free path needs no account and keeps the account list in the browser ("This device"). Sign in if you have early access; otherwise join the waitlist from the same dialog. Organizations (Pro, Team, Enterprise) are paid and add a shared account list. Never state prices.
- Lifecycle: Request, Wait, Review and approve, Execute, Record. Record statuses: UNDEFINED, PENDING, EXECUTING, COMPLETED, FAILED, CANCELLED (plus PROCESSING_PAYMENT).
- Execution paths: Delayed release (on-chain request, time lock, on-chain approve), Signed approval (on-chain request, off-chain signed approval, broadcaster submits), One signature (request and approval in one signature, broadcaster submits). Only Delayed release enforces the time lock.
- Roles: protected Owner, Broadcaster (1 to 3) and Recovery are set at deploy; custom roles hold signers. Actions are registered functions with per-step permissions across Request, Approval and Execute. Gates must be granted and are permanent for a role. Allowlists restrict native transfer recipients, attached-payment payees and contract targets; an empty allowlist denies everything.
- Signed files: a signed meta-transaction can be exported as a .bloxmeta.json file, imported in the Platform under Approvals > Import signed file, added to Approved, and executed by a wallet that may submit. Treat the file as a bearer instrument with a deadline; never put a payload in a URL.
- Pin @bloxchain/sdk and @bloxchain/contracts to the same Protocol release as the deployed contracts.

Docs: https://docs.bloxchain.app (index at /llms.txt, MCP at /~gitbook/mcp). API: /protocol/api-reference, /protocol/state-machine-engine, /protocol/meta-transactions.

Task: read account state

Task: Report owner, recovery, broadcasters, time lock, roles and open requests for the smart account at {ADDRESS} on Sepolia.

Use @bloxchain/sdk with a viem PublicClient only:
- SecureOwnable: owner(), getRecovery(), getBroadcasters(), getTimeLockPeriodSec()
- RuntimeRBAC: getSupportedRoles(), getRole(hash), getAuthorizedWallets(hash)
- BaseStateMachine: getPendingTransactions(), getTransaction(txId)
Pass the same account address and chain to every wrapper. No private key is needed.

Reference: /developers/sdk-setup, /developers/sdk-core-patterns, /protocol/api-reference

Task: prepare a request for a person to broadcast

Task: Prepare a governed request as a signed file that a person will review and broadcast. Do not submit anything on-chain.

Rules:
- You hold one narrowly permitted signer key (for example a requester-only custom role). You do not hold the Owner, Broadcaster or Recovery key, and you must not ask for one.
- Read the key from the runtime secret store at call time. Never write it into a prompt, a transcript, a log or a file you emit.
- You cannot widen your own access. If the policy denies the operation, stop and report which permission, gate or allowlist entry is missing.

Steps:
1. Read the account policy: the registered action and its per-step permissions, your role's gates, and the allowlist for the destination. Confirm your role holds the step you intend to sign.
2. Build the payload with MetaTransactionSigner (createUnsignedMetaTransactionForNew for a new request, createUnsignedMetaTransactionForExisting to approve or cancel one).
3. Use your current signer nonce, a short deadline, and a handlerSelector that matches the function the submitter will call.
4. Sign the contract-generated digest raw. Never personal_sign that digest.
5. Write the signed meta-transaction to a .bloxmeta.json file. Report, in plain text alongside it: action, destination, amount with decimals, network, account address, signer address and expiry.
6. Hand the file to the person. They import it under Approvals > Import signed file, check the decoded preview, choose Add to Approved, and execute it with a wallet that may submit.

The file is a bearer instrument until it expires or is used. Emit exactly one copy, over the channel you were told to use, and never in a URL.

Reference: /guides/agent-assisted-requests, /platform/operate/signed-files, /protocol/meta-transactions

Task: submit a governed transfer

Task: Move value out of the smart account through a registered action, respecting policy.

1. Confirm the calling wallet holds a role with the Request step on the action and that the role's gate is granted (RuntimeRBAC).
2. Confirm the recipient or target contract is on the account's allowlist (GuardController). An empty allowlist denies everything.
3. Delayed release: GuardController.executeWithTimeLock(...) creates a PENDING record; wait for releaseTime; a separate approver wallet calls approveTimeLockExecution(txId). Approving early reverts.
4. Signed approval or One signature: build the payload with MetaTransactionSigner, sign the raw digest (never personal_sign the digest), use the signer's current nonce and a short deadline, and submit from a wallet with the Broadcaster role. These paths do not wait for the time lock.
5. Wait for receipts, then read the record: COMPLETED means executed, FAILED means the guarded call reverted.

Reference: /introduction/how-it-works, /developers/sdk-core-patterns, /protocol/meta-transactions, /protocol/guard-controller

Task: review an integration for security invariants

Task: Review this code against Bloxchain security invariants.

Check:
- Least privilege per step; Owner, Broadcaster and Recovery keys are not used as day-to-day operator, service or agent keys.
- The broadcaster service holds only the Broadcaster role; approver keys are separate.
- SDK and contract versions pinned to the same Protocol release.
- Allowlists minimal; every action registered and its gate granted before use.
- Meta-transactions: raw EIP-712 digest signed, handler selector matches the submitting function, per-signer sequential nonce, short deadline.
- Signed files handled as bearer instruments: one copy, trusted channel, never in a URL, deleted after use or expiry.
- No reliance on an off-chain service (including the Platform) for authorization decisions.
- Keys in a secret store, not in .env files committed to source and not in an agent's prompt or logs.

Reference: /security/security-model, /security/security-best-practices, /guides/roles-and-permissions, /protocol/best-practices

Task: reproduce a Platform workflow in the SDK

Task: Reproduce what an operator does in the Bloxchain Platform, in code.

Map Platform areas to on-chain calls:
- Accounts > Deploy account: the official BasicFactory mints a BasicAccount for the sending wallet, which becomes the owner. Send directly from an EOA; salt 0 and a stepped index give a predictable address. CopyBlox and AccountBlox are the Sepolia developer toolkit, not the default (see /developers/deployment).
- Accounts > Import: nothing on chain; point the SDK at the existing address.
- On-chain access > Signers, Roles: RuntimeRBAC role configuration batches.
- Policies > Actions, Manage permissions, Gates: RuntimeRBAC function schemas and per-step permissions.
- Policies > Allowlists: GuardController target and recipient allowlists.
- Policies > Security: SecureOwnable owner transfer (time-locked), recovery, time lock and broadcaster updates (signed).
- New request, Approvals, History: EngineBlox record lifecycle (PENDING, EXECUTING, COMPLETED, FAILED, CANCELLED).
- Approvals > Import signed file: a .bloxmeta.json signed payload submitted by a wallet that may execute.

Reference: /platform, /platform/operate/approvals, /platform/policies/manage-permissions, /developers/configure-programmatically, /developers/sdk-core-patterns

Keeping prompts current

When this site paraphrases the Protocol, prefer the synced pages under /protocol/*. Versions and the documentation pin are on Releases and compatibility.

For humans

Start at What is Bloxchain? or the Developer quickstart.