> For the complete documentation index, see [llms.txt](https://docs.bloxchain.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloxchain.app/developers/for-ai-agents.md). # 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](/guides/agent-assisted-requests.md). ## Discovery | Resource | Where | Use | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | **llms.txt** | `/llms.txt` on the published site (also [llms.txt](https://github.com/PracticalParticle/bloxchain-docs/tree/main/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](https://github.com/PracticalParticle/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//
`. * 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](/resources/releases.md). ## 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 CopyBlox factory clones the AccountBlox template (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](/resources/releases.md). ## For humans Start at [What is Bloxchain?](/introduction/what-is-bloxchain.md) or the [Developer quickstart](/get-started/developer-quickstart.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bloxchain.app/developers/for-ai-agents.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.