portkey-ca-agent-skills

Portkey CA Agent Skill

Capabilities

• Auth operations: verifier, email code, register, recover, status
• Query operations: account, guardian, assets, chain config, transfer preflight
• Tx operations: transfer, contract call, approvals, keystore workflows
• Shared wallet context: auto-set active CA profile for cross-skill signer resolution
• Supports SDK, CLI, MCP, OpenClaw, and IronClaw integration from one codebase.

Online configuration

• Portkey CA currently supports mainnet only; the testnet deployment is decommissioned.
• Public services: AA API https://aa-portkey.portkey.finance, EOA asset fallback https://eoa-portkey.portkey.finance, and GraphQL https://indexer-api.aefinder.io/api/app/graphql/portkey.
• Chain RPC, CA contract, and default MultiToken addresses are returned by the Portkey chain-info API as endPoint, caContractAddress, and defaultToken.address; they are intentionally not duplicated as static deployment constants.
• Public account, chain, and asset reads need no local private key. Registration, recovery, and writes use an encrypted CA keystore or explicit signer variables listed in .env.example.
• PORTKEY_* overrides, AA-to-EOA fallback controls, and the shared wallet-context path are all included in the packaged .env.example.

Safe usage rules

• Never print private keys, mnemonics, or tokens in channel outputs.
• For write operations, require explicit user confirmation and validate parameters before sending transactions.
• Prefer read-only preflight checks first when available.
• Route Get* and other read-only contract methods through view-call / callContractViewMethod, not forward-call.
• Route forward-call / managerForwardCall only to state-changing methods.
• For Empty-input view methods such as GetConfig, omit params entirely so the runtime performs .call() with no arguments.
• Treat backend 3002 / Guardian not exist. as an unregistered account and route to register.
• Before transfer / cross-chain-transfer, run transfer-preflight to decide whether the path is:
  • direct transfer
  • one-time guardian approval
  • transfer-limit modification
  • wallet security upgrade / guardian sync
• Recommended stable write path is:
  • recover-and-save
  • poll manager-sync-status on the target chain
  • collect fresh transferApprove proofs
  • submit transfer / cross-chain-transfer with loginEmail + password
• Older AA/CA accounts recovered on AELF and then written on tDVV are a high-risk sync scenario; always check manager-sync-status before the first forward-call / claim / transfer on tDVV.
• transfer-preflight reports both the transferred asset balance and the chain default fee-token balance (feeSymbol / feeBalance / feeDecimals) when deciding one-time approval eligibility.
• send-code / verify-code support transferApprove for one-time transfer approval proof collection.
• transfer, cross-chain-transfer, and transfer-related forward-call accept optional guardiansApproved.
• transfer, cross-chain-transfer, and generic forward-call now block early when the current manager has not yet synced to the target chain.
• CLI write commands can resolve signer directly from CA keystore options (loginEmail / password / keystoreFile) instead of relying on a previous in-memory unlock.
• wallet-status returns recommendedAction / userHint when a local keystore exists but is still locked. recommendedAction=unlock is the next machine step; userHint explains how to verify the selected loginEmail / keystoreFile first and then route to recover-and-save only if the password was truly forgotten.
• VirtualTransactionCreated is forwarded-write evidence only; it is not a decoded view payload and not a standalone proof that a read-only contract query succeeded.

Command recipes

• Start MCP server: bun run mcp
• Run CLI entry: bun run portkey_query_skill.ts chain-info
• Run transfer preflight: bun run portkey_query_skill.ts transfer-preflight --ca-hash <hash> --ca-address <addr> --chain-id tDVV --symbol ELF --amount 100000000
• Run manager sync status: bun run portkey_query_skill.ts manager-sync-status --ca-hash <hash> --chain-id tDVV --manager-address <addr-from-recover-and-save-or-selected-signer>
• Read active wallet context: portkey_get_active_wallet
• Set active wallet context: portkey_set_active_wallet
• Install into IronClaw: bun run setup ironclaw
• Generate OpenClaw config: bun run build:openclaw
• Verify OpenClaw config: bun run build:openclaw:check
• Run CI coverage gate: bun run test:coverage:ci

Distribution / Activation

• GitHub repo/tree URLs are discovery-only for hosts and agents.
• Preferred IronClaw activation from npm: bunx -p @portkey/ca-agent-skills portkey-ca-setup ironclaw
• Preferred OpenClaw activation from npm when managed install is unavailable: bunx -p @portkey/ca-agent-skills portkey-ca-setup openclaw
• Local repo checkout is for development and smoke tests only.
• Migration note: portkey-setup was removed in 2.0.0; use portkey-ca-setup for npm-based activation.

Limits / Non-goals

• This skill focuses on domain operations and adapters; it is not a full wallet custody system.
• Do not hardcode environment secrets in source code or docs.
• Avoid bypassing validation for external service calls.
• Do not use this skill for EOA mnemonic/private-key wallet lifecycle flows.