---
name: use-agentshield
description: 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 needs to make, monitor, approve, or delegate 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.

## 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.
- 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

Default 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/`:

- `http://127.0.0.1:9400/skills/use-agentshield/SKILL.md`: save as `SKILL.md`
- `http://127.0.0.1:9400/skills/use-agentshield/references/api.md`: save as `references/api.md`
- `http://127.0.0.1:9400/skills/use-agentshield/scripts/agentshield.mjs`: save as `scripts/agentshield.mjs`
- `http://127.0.0.1:9400/skills/use-agentshield/agents/openai.yaml`: save as `agents/openai.yaml` (optional at runtime)

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

## 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 `@agentshield/sdk` instead of the helper when integrating AgentShield into an application. Keep the same authorization, idempotency, approval, and status-handling rules.

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.