Agent Wallet

intent

use this skill to safely create a wallet the agent can use for transfers, swaps, and any evm chain transaction without ever exposing private keys to the agent. create a wallet, set spending policies, and your agent can transfer tokens, do swaps, and interact with smart contracts within the boundaries you define. the agent never sees the private key. all transactions are executed server-side through a smart account. the wallet owner controls what the agent can do via configurable policies.

inputs

environment variables:

• SAFESKILLS_API_URL (optional): base api url for all wallet operations. defaults to https://safeskill-production.up.railway.app
• SAFESKILLS_FRONTEND_URL (optional): frontend url for wallet claim and policy management. defaults to https://safeskill-production.up.railway.app

external connection: SafeSkills API

• setup: deploy or access a running safeskills instance (zerodev-backed smart account infrastructure)
• auth: bearer token (api key returned on wallet creation)
• headers: Authorization: Bearer <API_KEY>, Content-Type: application/json

wallet creation inputs:

• type: EVM_WALLET (required)
• memo: optional label for the wallet (string, max 256 chars)
• chainId: numeric evm chain id (required). common values: 84532 (base sepolia), 1 (ethereum), 137 (polygon), 42161 (arbitrum), 10 (optimism), 8453 (base mainnet)

transaction inputs (transfers/swaps/calls):

• to: recipient address or contract address (0x-prefixed, 40 hex chars)
• amount: human-readable amount (string, e.g. "0.01" or "100")
• token: erc-20 token contract address (optional; omit for native eth)
• data: contract calldata (hex string, 0x-prefixed, for arbitrary transactions)
• value: native eth to send (string, wei or human-readable, defaults to "0")
• slippageBps: basis points for swap slippage tolerance (integer, optional, defaults to 100 = 1%)

user context:

• wallet owner email/identity (for claim url access)
• policy preferences (allowlists, spending limits, approval thresholds)
• target chain for operations

procedure

1. create wallet. post to ${SAFESKILLS_API_URL}/api/secrets with type EVM_WALLET, optional memo, and chainId. store the returned apiKey securely (this is your only auth credential for this wallet). capture the claimUrl and address from the response.

   • input: chainId (default 84532), memo (optional)
   • output: apiKey (string), claimUrl (url), address (0x-prefixed ethereum address)

2. share claim url with wallet owner. communicate the claimUrl to the user so they can claim ownership, set policies, and monitor activity. do not share the api key with the user.

   • input: claimUrl from step 1
   • output: none (user navigates url in browser)

3. fetch wallet address. if you need to confirm or retrieve the wallet address later, get it from ${SAFESKILLS_API_URL}/api/skills/evm-wallet/address using the api key as bearer token.

   • input: apiKey
   • output: address (0x-prefixed)

4. check balance (optional). query ${SAFESKILLS_API_URL}/api/skills/evm-wallet/balance to get native eth balance. optionally append query param ?tokens=0xAddr1,0xAddr2 to fetch erc-20 balances for specific token contracts.

   • input: apiKey, optional token addresses (comma-separated)
   • output: native balance (wei or human-readable), token balances (object keyed by token address)

5. preview swap (optional, before execute). post to ${SAFESKILLS_API_URL}/api/skills/evm-wallet/swap/preview with sellToken, buyToken, sellAmount, and chainId. this returns pricing and route info without executing.

   • input: sellToken (0x-prefixed address or 0xEee... for native eth), buyToken (0x-prefixed), sellAmount (human-readable string), chainId (integer), apiKey
   • output: expected buyAmount (string), route, gas estimate, fees

6. execute transfer or swap. for eth/token transfers, post to ${SAFESKILLS_API_URL}/api/skills/evm-wallet/transfer with to, amount, optional token address. for token swaps, post to ${SAFESKILLS_API_URL}/api/skills/evm-wallet/swap/execute with sellToken, buyToken, sellAmount, chainId, optional slippageBps.

   • input: apiKey, to/sellToken/buyToken (addresses), amount/sellAmount (string), optional token (transfer only), optional slippageBps (swap only)
   • output: txHash (string), status (pending, confirmed, or pending_approval), nonce

7. send arbitrary transaction (advanced). post to ${SAFESKILLS_API_URL}/api/skills/evm-wallet/send-transaction with to (contract address), data (calldata hex), optional value (native eth to send).

   • input: apiKey, to (0x-prefixed), data (0x-prefixed hex), value (wei or human-readable, optional)
   • output: txHash, status, nonce

8. handle pending approval status. if a transaction returns status: "pending_approval", the wallet owner will receive a telegram notification. wait for their approval or denial before retrying or escalating.

   • input: txHash from step 6 or 7
   • output: notification sent to owner; poll or wait for callback confirming approval

decision points

if wallet does not exist yet: create one (step 1). you must have an api key to proceed. if you lack safeskills credentials or deployment, you cannot operate this skill.

if transfer amount exceeds balance: the api will reject the request with a 400 error. inform the user to fund the wallet first or reduce the amount.

if transfer violates a policy (address allowlist, token allowlist, spending limit, etc.): the api returns 403 forbidden or status pending_approval. if denied outright, inform the user to check policies via the claim url. if pending approval, inform the owner via telegram and wait.

if swap preview returns zero or low buyAmount: liquidity may be insufficient, slippage too high, or the token pair unsupported. try a smaller sell amount, different chain, or different token pair.

if swap execute fails with "insufficient balance" or "allowance": ensure the wallet holds the sell token and that it has erc-20 approval for the smart account (the api handles this automatically for common dexes, but some contracts may require manual approval).

if api key is expired or revoked: all requests return 401 unauthorized. create a new wallet and regenerate the api key via the claim url.

if network timeout or 5xx error from safeskills api: retry with exponential backoff (wait 2s, then 4s, then 8s, max 3 retries). if persistent, check safeskills deployment status or contact the operator.

if the wallet owner has not claimed the wallet or set policies: all transactions are allowed by default. policies only take effect after the owner claims the wallet and configures them.

output contract

wallet creation response:

{
  "apiKey": "sk_live_...",
  "claimUrl": "https://safeskill-production.up.railway.app/claim/...",
  "address": "0x...",
  "chainId": 84532
}

balance response:

{
  "native": "1500000000000000000",
  "tokens": {
    "0xTokenAddr": "500000000"
  }
}

transfer/swap execute response:

{
  "txHash": "0x...",
  "status": "pending",
  "nonce": 5,
  "chainId": 84532
}

or

{
  "txHash": "0x...",
  "status": "pending_approval",
  "nonce": 6
}

arbitrary transaction response:

{
  "txHash": "0x...",
  "status": "confirmed",
  "nonce": 7,
  "gasUsed": "45000"
}

all responses include a status field: pending (submitted, awaiting confirmation), confirmed (on-chain), or pending_approval (awaiting owner approval). txHash is always a 0x-prefixed 64-character hex string. nonce tracks the wallet's transaction sequence.

outcome signal

wallet created successfully: you receive an apiKey, claimUrl, and address. the agent can now use the apiKey to sign requests.

owner claimed wallet: the claim url was accessed, and the owner set up policies. you see policy constraints reflected in api responses (e.g. 403 forbidden for disallowed addresses).

transaction executed: api returns status pending or confirmed and a txHash. you can query the tx on the evm block explorer using the txHash and chainId.

balance updated: you query the balance endpoint and see a balance change after a transfer or swap is confirmed (typically within a few blocks, 12-30 seconds on most evm chains).

swap preview succeeded: api returns expected buyAmount and route details. use this to confirm pricing with the user before executing.

transaction pending approval: api returns status pending_approval. the wallet owner receives a telegram message with approve/deny buttons. transaction settles once owner acts.

policy violation rejected: api returns 403 forbidden with a message indicating which policy was violated (e.g. "spending limit exceeded" or "address not in allowlist"). user can adjust policies and retry.