# Convex Peer Server

> The Engine of the Agentic Economy

This is a **TEST** Convex peer at https://mikera1337-convex-testnet.hf.space connected to a test network.

Coins on this network have no real value. This peer may have a faucet available
for free test coins via the `createAccount` MCP tool with a `faucet` parameter.

For the live network with real Convex Coins, use: https://peer.convex.live

## Peer Info

- Network: Test Network
- Peer Key: ff5671e6242112b706bb4ba47507ac1e90c00bf223e2df043b9b25b50a00ba60
- Genesis Hash: 0x72738e0e66eed1fa3e9c985a2aa0e440948a32c5bb088536d31a1d2d7ba06646
- API Base: https://mikera1337-convex-testnet.hf.space
- MCP Endpoint: https://mikera1337-convex-testnet.hf.space/mcp (POST JSON-RPC)
- REST API: https://mikera1337-convex-testnet.hf.space/api/v1/
- Explorer: https://mikera1337-convex-testnet.hf.space/explorer/

## MCP Tools Available

This peer exposes Model Context Protocol tools for AI agents:

- **query**: Execute a Convex Lisp query. Queries are read-only, free, and instant.

Common patterns:
- (balance #13) — coin balance in copper (1 CVM = 1,000,000,000 copper)
- *balance* — caller's own balance
- (account #13) — full account record
- (@convex.fungible/balance #TOKEN #USER) — fungible token balance
- (call #ACTOR (fn-name args)) — call actor function read-only
- (lookup #ADDR 'symbol) — look up a definition
- *state* — full network state (large!)
- **prepare**: Prepare a Convex transaction for signing. Returns a hash to pass to 'signAndSubmit' or 'submit'.

Common source patterns:
- Transfer: (transfer #DEST AMOUNT)
- Deploy actor: (deploy '(do (defn greet [x] (str "Hello " x)) (export greet)))
- Call actor: (call #ACTOR (function-name arg1 arg2))
- Define value: (def my-var 42)
- Set controller: (set-controller #ADDR)
- Register CNS: (call #9 (cns-update 'my.name *address*))

Amounts in copper (1 CVM = 1,000,000,000 copper).
- **transact**: Execute a Convex transaction in one step. Sends seed over network — use HTTPS with trusted peers only. For sensitive operations prefer prepare → signAndSubmit.

Transactions update global state atomically. Amounts in copper (1 CVM = 1,000,000,000 copper).
- **encode**: Encode a CVM literal into CAD3 multi-cell hex bytes.
- **decode**: Decode CAD3 multi-cell hex bytes back into a CVM literal.
- **submit**: Submit a previously prepared transaction with hash, public key, and signature.
- **signAndSubmit**: Sign and submit a prepared transaction. Use after 'prepare'. Sends seed over network — HTTPS only.
- **hash**: Compute a SHA-256 or SHA3 hash of supplied data.
- **sign**: Sign raw hex data with an Ed25519 seed. For transactions, sign the 'hash' from prepare.
- **peerStatus**: Return current Convex peer status including consensus point and network state.
- **keyGen**: Generate a new Ed25519 key pair. Provide a seed for deterministic output, or omit for secure random.
- **validate**: Validate an Ed25519 signature against a public key and message bytes.
- **createAccount**: Create a new Convex account with the specified public key. Optionally fund via faucet (1 CVM = 1,000,000,000 copper, max 1 CVM).
- **describeAccount**: Get account info: balance, sequence number, defined symbols with metadata.
- **lookup**: Look up a symbol in a Convex account environment. Returns existence, value (with optional path navigation), and metadata.
- **resolveCNS**: Resolve a CNS name to its record: value (usually an address), controller, metadata, and child node.
- **getTransaction**: Look up a transaction by hash. Returns signed data, consensus position, and execution result.
- **getBalance**: Get coin or token balance for an account. Returns balance in copper (1 CVM = 1,000,000,000 copper).
- **transfer**: Transfer CVM coins or fungible tokens to another account. Amounts in copper for CVM (1 CVM = 1,000,000,000 copper).
- **watchState**: Watch a path in the global CVM state for changes. Returns a watchId. Changes are delivered as SSE notifications on the session's GET /mcp stream. Requires an active session (Mcp-Session-Id).
- **unwatchState**: Stop watching state paths. Provide a watchId to remove a single watch, or a path to remove all watches whose path starts with the given prefix. At least one of watchId or path must be provided.
- **signingServiceInfo**: Check if the peer's signing service is available. No authentication required.
- **signingCreateKey**: Create a new Ed25519 key pair in the signing service. Private key stored encrypted server-side. Authenticated.
- **signingListKeys**: List all public keys stored in the signing service for the authenticated identity.
- **signingSign**: Sign hex-encoded bytes using a stored signing service key. Authenticated.
- **signingGetJWT**: Create a self-signed EdDSA JWT (did:key identity) using a stored signing key. Authenticated.
- **signingTransact**: Execute a Convex transaction using a stored signing key. Private key never leaves the server. Authenticated.
- **signingCreateAccount**: Create a new signing key and on-chain account in one step. Optionally fund via faucet. Authenticated.
- **signingListAccounts**: List signing keys and associated on-chain addresses for the authenticated identity.
- **signingImportKey**: Import an Ed25519 seed into the signing service. Elevated: first call returns confirmUrl for browser approval, retry with confirmToken.
- **signingExportKey**: Export (reveal) the private seed for a stored key. Elevated: first call returns confirmUrl, retry with confirmToken.
- **signingDeleteKey**: Permanently delete a key from the signing service. Irreversible. Elevated: first call returns confirmUrl, retry with confirmToken.
- **signingChangePassphrase**: Change the passphrase for a stored signing key. Elevated: first call returns confirmUrl, retry with confirmToken.

## Agent Capabilities

1. **Free test coins**: Use the faucet to get free test coins for experimentation.
   Perfect for development and testing agent workflows.

2. **Persistent identity & memory**: Agents get permanent Addresses (e.g. #1465) that survive
   across sessions. On-chain key-value storage acts as infinite tamper-proof memory.

3. **Autonomous execution**: Deploy agents as Convex actors that run forever.
   React to on-chain events and compose with any other agent permissionlessly.

4. **Zero-fee reads**: Query the entire world state for free. Use the faucet for test coins.

## Quick Start for Agents

```bash
# Query (free, read-only)
curl -X POST https://mikera1337-convex-testnet.hf.space/api/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"source": "(+ 1 2)", "address": "#11"}'

# MCP Tool Call
curl -X POST https://mikera1337-convex-testnet.hf.space/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"query","arguments":{"source":"*balance*"}},"id":1}'
```

## References

- [Convex World](https://convex.world) — Engine for the agentic economy
- [Documentation](https://docs.convex.world) — Build Autonomous Agents
- [Explorer](https://mikera1337-convex-testnet.hf.space/explorer/) — Watch Agents Trade and Govern
- [Protonet](https://peer.convex.live) — Official live Protonet peer hosted by Convex Foundation
- [GitHub](https://github.com/Convex-Dev) — Open Source Runtime & SDKs
- [Discord](https://discord.com/invite/xfYGq4CT7v) — Join the Builder Community