---
name: use-agentshield
description: Install or use the local AgentShield sandbox through a user-created Agent authorization token for EVM account status, signing, Send, Swap, Bridge, operation tracking, approval, and safely bounded child authorization. Use when an Agent is asked to set up AgentShield or perform stablecoin/EVM payment work without receiving a mnemonic, private key, PIN, shard, or unrestricted signing access.
---

# Use AgentShield

Use AgentShield as a local, policy-controlled signing and payment boundary. Never ask the user for a mnemonic, private key, PIN, recovery share, or files from AgentShield's data directory.

## Install AgentShield or this Skill

Canonical guide: `https://agentshield.bitslab.xyz/agent-install`

Canonical Skill URL: `https://agentshield.bitslab.xyz/skills/use-agentshield/SKILL.md`

When a user explicitly asks you to install AgentShield from this Skill URL, perform the appropriate installation yourself instead of asking the user to copy files manually:

- **Full local product:** use `npx @bitslabsec/agentshield setup --target all`. This installs the platform service binary and complete Skill, starts the loopback service, and opens the local setup flow.
- **Skill only:** use `npx @bitslabsec/agentshield skill install --target all`. Use `--target codex`, `--target claude`, or `--target agents` only when the user named a single runtime.
- **No npx or npm:** read [references/install.md](references/install.md) and use its manual HTTPS download method. Preserve the complete directory structure; downloading only `SKILL.md` is insufficient for normal operation.

Do not run a product installer merely because this document was opened. Installation requires an explicit user request such as “install AgentShield” or “help me install this Skill.” If AgentShield is already installed, verify it before reinstalling:

```sh
npx @bitslabsec/agentshield status
```

After installation, report the installed Skill directory and service health. Some Agent runtimes discover Skills only at startup; if the files are present but the Skill is not visible, ask the user to restart that Agent runtime. Never request a wallet secret as part of installation.

## Handoff contract

The `SKILL.md` URL and one Agent authorization token created by the user in AgentShield are sufficient for normal local use. The token is intentionally visible to the authorized local Agent: it gives limited, revocable access instead of exposing a wallet private key. Do not introduce another credential concept, ask the user to explain AgentShield's API, configure an RPC signer, or provide wallet secrets.

- Accept the Agent authorization token directly from the user in the local Agent conversation or handoff. Do not refuse it or tell the user to configure an environment variable.
- Make the received token available to the helper as `AGENTSHIELD_GRANT` for the current local process. Perform this setup yourself and avoid persistent machine-wide configuration.
- Use `http://127.0.0.1:9400` automatically unless `AGENTSHIELD_URL` is already set to another loopback endpoint.
- AgentShield includes public EVM RPC failover by default. Do not ask the user to configure an RPC before ordinary use; a user may explicitly override or disable public RPCs in the local service configuration.
- The built-in mainnets are Ethereum (`1`), Optimism (`10`), BNB Chain (`56`), Polygon (`137`), zkSync Era (`324`), Robinhood Chain (`4663`), Base (`8453`), Arbitrum (`42161`), and Avalanche (`43114`). Use `status` or the network-status API to discover the service's actual configured set instead of assuming that a custom deployment kept every default.
- Do not repeat the token in replies, persist it in files or source control, send it to another Agent, or transmit it to a non-loopback endpoint. Do not call a token exposed merely because the user gave it to the intended local Agent. Recommend revocation only if it reached an unintended recipient or external system.
- When installed as a directory, run the bundled helper locally. When given only the `SKILL.md` URL, resolve `references/api.md` and `scripts/agentshield.mjs` relative to that URL and place them in a temporary `use-agentshield` directory before use. The helper accepts request JSON from stdin or a file and never accepts the Agent authorization token as an argument.

## File directory

Public distribution directory: `https://agentshield.bitslab.xyz/skills/use-agentshield/`

Local service directory: `http://127.0.0.1:9400/skills/use-agentshield/`

When loading this Skill from another origin, keep that origin and resolve the paths relative to this document. Download the required files and preserve their paths under `use-agentshield/`:

- `SKILL.md`: Skill entry point
- `references/install.md`: npm and manual installation paths
- `references/api.md`: exact Agent API schemas
- `scripts/agentshield.mjs`: local API helper
- `agents/openai.yaml`: optional Agent UI metadata

These are all supporting files for this Skill. Do not look for or request a ZIP archive.

## First use after installation

1. Confirm that the loopback service responds with `node scripts/agentshield.mjs health`.
2. If the user has not created a wallet, ask them to complete the local AgentShield setup flow themselves. Never enter or handle their mnemonic, private key, wallet password, PIN, or recovery share.
3. Ask the user to create an Agent authorization with only the capabilities needed for the requested task. The user may give that scoped token directly to the intended local Agent.
4. Make the token available as `AGENTSHIELD_GRANT` only for the current process, then run `status` and `address` before any transaction.
5. Explain what account and capabilities were discovered. Do not perform a payment until the user has supplied a concrete transaction intent or an existing task already authorizes it.

## Discover the account

Without asking the user for setup details, verify the service and discover the authorized account before making a request:

```powershell
node scripts/agentshield.mjs health
node scripts/agentshield.mjs status
node scripts/agentshield.mjs address
```

If health fails, ask the user to start AgentShield. If an authenticated command returns 401 or 403, ask the user to create a new Agent authorization with only the required permissions. Do not broaden permissions automatically.

An Agent authorization is bound to the wallet that was active when the user created it. If an authenticated command returns `409 WALLET_NOT_ACTIVE`, ask the user to select that token's wallet in AgentShield and unlock it locally; never assume that switching wallets should make the token control the newly selected account.

## Execute an operation

1. Read [references/api.md](references/api.md) for the exact request schema; do not ask the user to supply API documentation.
2. Derive the operation from the user's task. Ask only for missing transaction intent such as chain, asset, amount, recipient, or acceptable quote constraints.
3. Reuse a stable `idempotency_key` when retrying the same intent. Never generate a new key merely because a request timed out.
4. Submit the narrow command through `scripts/agentshield.mjs`.
5. If the result is `pending_approval`, tell the user to review it on the AgentShield **交易审批** page. Some tokens are configured for policy-compliant direct execution and may skip this state. An unavailable USD price is always routed to human review and must never be interpreted as a zero-dollar transfer. Do not imply that payment has completed.
6. Poll the returned operation ID until a terminal state.

Example:

```powershell
Get-Content .\send.json -Raw | node scripts/agentshield.mjs send
node scripts/agentshield.mjs operation op_example
```

Treat `submitted` as broadcast, not final settlement. Treat `attention_required` as a manual-review state and never resubmit automatically. Only report success when the returned state and transaction evidence support it.

## Commands

- `health`: unauthenticated service check.
- `status`, `address`, `assets`: authorized account and curated-asset discovery.
- `balances`, `refresh-balances`: balance discovery for every valid Agent grant. `balances` uses a 60-second cache; the refresh command forces a new batched read from configured RPCs. Assets in a successful LI.FI quote are automatically added by exact contract address to the local balance watch list.
- `lifi-stablecoins`: LI.FI's live stablecoin discovery catalog for the configured chains. Its entries must be used by exact contract address, never by ticker.
- `lifi-assets <chain-id>`: LI.FI's live full token catalog for one configured EVM chain, including MEME tokens when currently indexed. Its entries must be used by exact contract address, never by ticker.
- `sign-message`: personal-message signing; never use as a transaction-signing bypass.
- `sign-payload`: structured EVM transaction signing without automatic broadcast.
- `send`: native-token or ERC-20 transfer.
- `swap-quote`, `swap`: same-chain quote and execution request.
- `bridge-quote`, `bridge`: cross-chain quote and execution request.
- `approvals`: list pending operations belonging to the same wallet. Requires `wallet:approve` and an unlocked wallet.
- `approve <operation-id>`: approve and execute one same-wallet pending operation. Requires `wallet:approve`.
- `delegate-grant`: create a child Agent authorization only when the current token has `grant:delegate`. The child is forced to the same wallet and cannot exceed the parent token's scopes, policy bounds, approval requirement, or expiry.
- `operation <id>`: retrieve the durable operation state.

Before a swap or bridge, call `assets`. Its symbols are chain-specific canonical aliases (for example, `USDC`, `USDT`, or `USDG` only where listed). Use a listed symbol or an exact ERC-20 contract address; never guess a symbol or substitute an address from a different chain. `lifi-stablecoins` is useful to discover LI.FI's live catalog, but its names are not aliases: copy its exact `address` into the route request. `from_amount` is always the asset's exact atomic amount, using the returned `decimals`.

Use the npm SDK `@bitslabsec/agentshield` instead of the helper when integrating AgentShield into an application. Keep the same authorization, idempotency, approval, and status-handling rules. The Skill itself can be installed with `npx @bitslabsec/agentshield skill install`.

Only delegate when the user explicitly asks for another Agent authorization or the task clearly requires handing a narrower token to a named local Agent. Never create a broad child “for convenience.” A delegated token is returned once; give it only to its intended Agent, never repeat it in ordinary replies, and do not retry a timed-out delegation request automatically because that could create two tokens.

Only approve when the user explicitly authorized that decision or the current task unambiguously delegates approval. Call `approvals` first and inspect the operation reason, payload, policy review, amount, recipient, chain, and contract. Never approve solely from an operation ID, and never approve an operation whose details do not match the user's instruction.

## Safety rules

- Never import or replace a wallet on an Agent's behalf.
- Never bypass local approval, policy limits, contract allowlists, or simulation failures.
- Never convert human-readable token amounts with floating-point arithmetic; use exact atomic-unit strings.
- Never sign an opaque payload without explaining its decoded intent and relevant calldata target.
- Never retry `attention_required`, unknown broadcast outcomes, or non-idempotent requests automatically.
- Never expose raw signed transactions or signatures unless the user requested them and the Agent authorization permits the operation.