---
name: agentswallet-si
description: Noncustodial agent-only API for registering locally generated crypto wallet public addresses on supported chains and discovering listed assets. No human UI or private key custody.
homepage: https://agentswallet.si
---

# AgentsWallet.si — Agent Skill

**Service:** https://agentswallet.si

This API **does not generate private keys or create funded/usable chain accounts**. The agent creates its own actual wallet keys using a vetted chain-specific cryptographic library or secure signer in its own runtime. Keep its seed phrase, private keys, and Ed25519 identity secret **outside model prompts, conversations, browser pages, HTTP request bodies, logs, and WordPress**. Store and back them up securely. Lost keys cannot be recovered here.

An agent must have an external-action capability (HTTP, shell, MCP tool bridge, or SDK) to use this API. These instructions do not themselves create a wallet. There is **no browser Create Wallet button or Reown connection**. Being a human cannot be cryptographically ruled out by an API-only interface.

## API workflow

1. **Generate and store an Ed25519 identity key locally**, separately from blockchain signing keys. Record the public key (base64 32 bytes). Never send the private key. Your model name is a display label, not a unique identity.
2. `POST https://agentswallet.si/wp-json/agentswallet/v1/registration-challenge` with `{}`. Store the returned one-use nonce (valid 5 minutes).
3. Sign the exact UTF-8 text `AgentsWallet.si agent registration v1\n<nonce>\n<agent_name>\n<public_key_base64>` with your local Ed25519 identity private key. Substitute actual values and actual newline bytes, not backslash-n strings.
4. `POST https://agentswallet.si/wp-json/agentswallet/v1/agents` with `{"name":"Your Agent Model Name","public_key":"<base64-32-byte-key>","nonce":"<nonce>","signature":"<base64-64-byte-ed25519-signature>"}`.
5. Store the one-time `api_token` securely in your agent runtime. It is an **API credential, not a blockchain wallet private key**. Do not place it in prompts.
6. Generate chain-specific signing keys and derive a public receiving address locally using a verified blockchain SDK/signer. **Never send signing keys to AgentsWallet.si.**
7. `GET https://agentswallet.si/wp-json/agentswallet/v1/catalog` to discover supported chain IDs and token contracts/mints. Catalog presence does not prove token legitimacy, bridge availability, or that deposits can be tracked.
8. `POST https://agentswallet.si/wp-json/agentswallet/v1/wallets` using `Authorization: Bearer <api_token>` and JSON `{"network":"eip155:8453","address":"0x..."}`. Use an actual valid address on that network. Registration by itself never proves signing-key control. For Solana or EVM EOA addresses, follow the applicable optional proof flow below.
9. `GET https://agentswallet.si/wp-json/agentswallet/v1/wallets` (same bearer) to list your registered public receiving addresses. Multiple networks/addresses are allowed. Entries report `registered` or `retired`, `ownership_verified`, `verification_scheme`, and `verified_at`. A `true` proof means **limited signing-key control** (Solana Ed25519, or EVM EOA proof through a trusted RPC), not that deposits, balances, tokens, account existence, or legal identity have been verified.
10. To retire an address no longer intended for use, call `DELETE https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>` with your bearer token. The original record is retained for audit. **Retiring an address here does not revoke blockchain keys, stop third-party deposits, or recover funds.** The same retired record cannot silently be reactivated.
11. `GET https://agentswallet.si/wp-json/agentswallet/v1/events?limit=20` with bearer token lists recent registration, retirement and credential audit events. This is not a blockchain transaction ledger.

## Prove signing-key control of a Solana receiving address (optional)

This flow is supported **only for `solana:mainnet` Ed25519 addresses**. EVM EOA proof is separately described below; Bitcoin ownership proof remains unavailable. No private key is sent to WordPress. A Solana program-derived address, multisig, or other non-signing address may be valid for certain purposes but cannot complete this direct signing-key proof.

1. Register a Solana address normally using `POST /wp-json/agentswallet/v1/wallets` with `{"network":"solana:mainnet","address":"<base58-Solana-public-key>"}`. Save the returned `id` as your `<wallet_id>`.
2. `POST https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/ownership-challenge` with your **agent API bearer token**, and an empty JSON object. This issues a five-minute, single-use nonce tied to the **specific agent ID and wallet ID**.
3. The response contains exact `message` (UTF-8 text) and `message_base64` (the same bytes). **Sign exactly those bytes in your own secure Solana signer** using the wallet key associated with the registered address. The server does not accept your private key. The message binds the current site URL, agent ID, wallet ID, network, address, and nonce; do not reconstruct or alter it.
4. `POST https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/verify-ownership` using bearer authentication and JSON `{"nonce":"<nonce>","signature":"<canonical base64 of the 64-byte detached Ed25519 signature>"}`.
5. A successful result records `ownership_verified: true`, `verification_scheme: "solana-ed25519-v1"`, and a timestamp. The challenge can never be reused. You may request another one if you need to prove control again.

**Scope:** This verifies possession of the signing key corresponding to the Solana address. It does **not** query Solana RPC, confirm on-chain balances, check whether the account is funded, validate tokens or associated token accounts, or establish who legally owns the key. EVM EOAs have a separate optional RPC-backed proof flow. Bitcoin and EVM smart-contract wallets remain unverified. Retired wallet records cannot be verified. No live transfers exist.

## Prove signing-key control of an EVM EOA receiving address (optional, trusted RPC required)

EVM support includes **only externally owned addresses (EOAs)** on enabled EVM chains (e.g. Ethereum, Base, Polygon, Arbitrum, Optimism). EVM contract wallets/EIP-1271 and Bitcoin do not have signing-key proof support. The administrator must first configure a **trusted public HTTPS chain RPC** for the chosen EVM network. Without one, this proof is unavailable and registration remains unverified. The service does not receive or store any private signing key.

1. Generate an EVM private key and address **locally in your secure signer**. Register the public address on the desired enabled chain using `POST /wallets` with `{ "network":"eip155:8453", "address":"0x..." }` as an example. Save the returned wallet `id`.
2. Issue `POST https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/ownership-challenge` with the agent API bearer token. Receive the exact `message`, `message_base64`, `nonce`, and `signature_scheme`. Challenge expires in five minutes.
3. Sign the **exact UTF-8 `message` bytes using EIP-191 `personal_sign`** with the registered EVM address's private signing key. Do *not* sign a reconstructed message, sign a transaction, or send the key to AgentsWallet. Signature format: 65-byte `(r,s,v)` in `0x`-prefixed hex, canonical low-s, recovery `v` 0/1 or 27/28.
4. Submit `POST https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/verify-ownership` with bearer and JSON `{ "nonce":"<nonce>","signature":"0x<130 hex digits>" }`. A valid proof returns `ownership_verified:true`, `verification_scheme:"evm-eip191-eoa-rpc-v1"`, and a timestamp. The challenge is single-use; reuse, expiry, wrong chain, wrong wallet, other agent, and invalid signatures fail.

**Trust and scope:** The server uses the configured trusted RPC to check `eth_chainId`, calculate the EIP-191 `Keccak-256` hash (`web3_sha3`) and recover an EOA address with `eth_call` to the ecrecover precompile. It accepts the proof only when the recovered address matches the registered address. A dishonest provider could falsify responses; this version cannot independently prove RPC honesty. The check is a snapshot, **not** proof of token validity, funds, ability to receive a particular token, contract-wallet ownership, on-chain account state, or continual key control. No transfers or deposit monitoring are enabled.

## Query a read-only EVM balance snapshot (optional)

**Only enabled EVM chains with an administrator-configured trusted HTTPS RPC are supported in this release.** This operation does not require submitting a blockchain signature or private key, and it never transfers funds. It is not continuous balance tracking or deposit monitoring. Solana addresses can now be queried on the same route using a separately configured Solana RPC. Bitcoin mainnet native BTC snapshots are optionally available through an administrator-configured Esplora indexer; no key proof for Bitcoin.

1. Register your EVM receiving address (`POST /wallets`). This is required even though chain state is publicly readable; the API checks that the wallet belongs to the authenticated agent.
2. Query the **native asset** using `GET https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/balances` with `Authorization: Bearer <api_token>`.
3. For a configured ERC-20 token, get its `id` on the *same network* using `GET /catalog`, then request `GET https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/balances?asset_id=<catalog_asset_id>` with the agent bearer token. Requests for assets belonging to a different network are rejected.
4. Response has string-valued `balance_base_units` (exact decimal integer, no floating-point conversion), `balance_display` (decimal display according to the configured catalog metadata), `snapshot_block` (hex block number), `observed_at`, and `rpc_chain_matched:true`. These are **reported by the configured RPC**, not independently verified against multiple nodes.
5. Error or unconfigured RPC means **unknown balance**, not zero. Calls to a retired wallet, another agent's wallet, unsupported networks, malformed contracts, or wrong-chain asset IDs are rejected. RPC calls are rate limited and results are not stored in the WordPress database.

**Risk:** A malicious/stale RPC can lie, chain reorganizations can change balances, an ERC-20 contract can have deceptive behavior, and catalog symbol/decimals are administrator-supplied rather than on-chain-verified. Never treat a snapshot as proof of receipt, settlement, token legitimacy or spendable funds. This release does not monitor incoming deposits, sign transactions, broadcast transfers, or perform sanctions checks for agent-side transfers. Outgoing transfers must use a signer with mandatory sanctions enforcement.

## Query a read-only Solana SOL or SPL token balance (v0.1.8)

**Solana mainnet only**, with an administrator-configured trusted public HTTPS Solana JSON-RPC endpoint. The same authenticated route is used as for EVM; no new API credential or key is required. This is a point-in-time observation, **not deposit monitoring or proof of settlement**.

1. Generate and safeguard the Solana signing key in your own runtime, then register your Solana public address with `POST /wallets` on `solana:mainnet`. Ownership proof is optional and does not itself query balances.
2. Request native **SOL** using `GET https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/balances`, with your agent bearer token. The plugin first checks the RPC `getGenesisHash` against the established Solana mainnet hash, then calls `getBalance` with `finalized` commitment.
3. For an SPL token, use `GET /catalog` to find the **registered mint's** `asset_id` on `solana:mainnet`. Call `GET https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/balances?asset_id=<asset_id>`. It checks the mint account and mint decimals, then requests `getTokenAccountsByOwner` filtered by the mint and sums matching token-account balances. Both the legacy SPL Token Program and Token-2022 are supported where the RPC returns supported parsed data.
4. The API returns exact string fields `balance_base_units` and `balance_display`, `snapshot_slot`, `commitment: finalized`, `rpc_genesis_matched: true`, and for tokens also `mint_lookup_slot`, `token_program`, and `token_accounts_count`. Each RPC call may observe a different slot; these are **not atomic or independently verified**.
5. If the RPC is absent, wrong-chain, unavailable, gives invalid data, or the catalog token decimals differ from the RPC-reported mint decimals, the request fails rather than inventing a zero balance. No cached balances, signing, sending, swap, bridge, or sanctions-enforced external transaction control is provided.

**Token-2022 caution:** Transfer fees, freezing, confidential balances, transfer hooks, or other extensions can affect usable or transferable funds; a raw token balance is not necessarily spendable. A wallet can have multiple token accounts for one mint. Mint name/symbol and token authenticity are not independently validated, and a malicious RPC can lie.

## Lost API token? Recover access using the existing agent identity key

Keep the Ed25519 **agent identity private key** securely as well as any separate blockchain wallet keys. Unlike a lost API bearer token, a lost identity key **cannot** be recovered by this API.

1. `POST https://agentswallet.si/wp-json/agentswallet/v1/credential-challenge` with JSON `{"agent_id":123}`. Record the returned five-minute, one-use `nonce` and the stored `public_key`.
2. Sign **exact UTF-8 bytes** of `AgentsWallet.si API credential rotation v1\n<nonce>\n<agent_id>\n<identity_public_key_base64>` using the saved Ed25519 agent identity private key. Replace `\n` with newline bytes; use the decimal ID as shown in the response.
3. `POST https://agentswallet.si/wp-json/agentswallet/v1/rotate-credential` with `{"agent_id":123,"nonce":"<nonce>","signature":"<canonical base64 Ed25519 signature>"}`.
4. Save the new one-time `api_token` in secure storage. The previous token is immediately invalidated. No blockchain wallet key or receiving address is changed. The same nonce cannot be reused.

Both token issuance and recovery responses are marked `Cache-Control: no-store`. Never submit a private key to the service. If the original identity key is lost, use a newly registered agent identity and separately verify ownership of any associated chain wallets; the API will not transfer another agent's records based only on a display name.

## Supported network formats

`eip155:<positive chain ID>` (enabled EVM networks), `solana:mainnet`, `bitcoin:mainnet`. `GET /catalog` is authoritative for currently enabled networks/assets. Assets use **(network, identifier)**, where identifier is `native` or a token contract/mint; symbols alone are not authoritative. Not all network and token combinations are enabled.

## Safety and limitations

- This registry **never** handles private/seed keys, signs, broadcasts, holds funds, or recovers lost keys. Never post a mnemonic, seed phrase, or private key. A new API token is not a replacement for the blockchain private key.
- API registration is **not proof you control a blockchain address**; only a successful optional Solana or RPC-backed EVM EOA signing-key proof verifies that limited fact. Bitcoin and EVM contract wallets remain unverified. Verify network/token compatibility independently before requesting payment. For Solana tokens, associated token accounts can be required.
- This version cannot observe deposits, show independently verified balances, execute spending, or provide a custody guarantee. Authenticated EVM/Solana balance snapshots and optional Bitcoin mainnet address reports are unverified read-only provider observations, not deposit monitoring. No funds should be sent solely because an address was registered here.
- Any future payment flow involving this service must pass fresh sanctions screening including recipient address, counterparty, jurisdiction, asset, and relevant network; fail closed on unavailability. The optional legacy `/payment-intents` route creates **screening-only records**, never live transactions. An external signer could bypass this API, so independent signer-side enforcement is needed for compliant automated sending.
- Private keys saved in a model's conversation or an unprotected file are susceptible to theft and unintended disclosure. Use a proper encrypted keystore, KMS, hardware device, or other agent-controlled secure signer when possible.
- No human/AI attestation is performed; API-only access is intended for agents, not proof of agenthood.

## Other discovery resources

- `https://agentswallet.si/llms.txt`
- `https://agentswallet.si/.well-known/agentswallet.json` (if host permits `.well-known` rewrites)
- `https://agentswallet.si/wp-json/agentswallet/v1/discovery` (reliable fallback)

## What to tell users

> Your private key controls your cryptocurrency. Store it securely and never share it. AgentsWallet.si cannot recover lost keys or reverse transactions.


## Read a Bitcoin mainnet native-BTC balance snapshot (v0.1.9, optional)

1. Generate your own Bitcoin signing key in a secure agent-controlled environment, derive a **Bitcoin mainnet** receiving address, and register it with the authenticated wallet API using network `bitcoin:mainnet`. Registering an address does **not** prove key control; Bitcoin ownership verification remains unsupported. Never send keys or seed phrases to AgentsWallet.
2. With your existing agent bearer token, call `GET https://agentswallet.si/wp-json/agentswallet/v1/wallets/<wallet_id>/balances` for that registered, active BTC address. Omit `asset_id` for the native BTC asset. If `asset_id` is given, it must refer to that chain's **native BTC** catalog entry.
3. This endpoint only works when a WordPress administrator has configured a trusted **HTTPS Esplora API mainnet indexer**. No configured indexer, wrong genesis hash, unreachable indexer or malformed data means **balance unavailable**, not zero. WordPress never exposes its configured URL in agent discovery.
4. Successful responses include `balance_base_units` (exact confirmed satoshis), `balance_display` (BTC), `confirmed_balance_sats`, signed `mempool_delta_sats`, `projected_balance_sats`, `projected_balance_display`, `snapshot_tip_height`, `observed_at`, `indexer_genesis_matched`, and the `indexer_reported_not_independently_verified` status. All monetary quantities are decimal strings; do not use floating point for satoshis.
5. This is **one address** of your wallet, not an HD wallet aggregate and not an independently verified proof of funds, spendable UTXOs, incoming deposit reconciliation or transfer settlement. Mempool transactions may be dropped, replaced or reorganized; the genesis check does not make a malicious indexer trustworthy. A third-party indexer can learn queried addresses. No Bitcoin signing or sending API is implemented. The 100/hour per-agent balance lookup limit remains shared across supported chains.