wallet

Files (1)

• SKILL.md

SKILL.md (first lines)

# BRC-100 Wallet Endpoints

`wallet_call` is a generic bridge to the local BRC-100 wallet. One tool, any endpoint.

```json
wallet_call({"endpoint": "discoverByIdentityKey", "params": {"identityKey": "03...", "limit": 10}})
```

## Common Workflows

### Receive BSV from Anyone

Use `receive_address` (discoverable via `search_tools`) to generate a BSV address:

```json
receive_address({"suffix": "1"})
// → { "address": "1A1zP1...", "public_key": "03...", "suffix": "1" }
```

Share the address with the sender. After they send, internalize via one of two paths:

**If the sender gives you the BEEF directly** (e.g. via chat or MessageBox):
```json
fund_from_tx({"beef_hex": "0100beef...", "vout": 0, "suffix": "1"})
```

**If you only have the txid** (fetch BEEF from WhatsOnChain):
```json
fund_from_tx({"txid": "abc123...64hex...", "vout": 0, "suffix": "1"})
```

The `suffix` must match between `receive_address` and `fund_from_tx`. Use different suffixes to generate different addresses (e.g. for different senders or purposes).

### Send BSV to an Address

Use `wallet_call` with `createAction` to build and broadcast a payment:

```json
wallet_call({"endpoint": "createAction", "params": {
  "description": "Send 10000 sats",
  "outputs": [{"lockingScript": "76a914<hash160>88ac", "satoshis": 10000, "outputDescription": "payment"}]
}})
```

### Create an On-Chain OP_RETURN Proof

To record data on-chain via OP_RETURN, build the locking script as `006a` + push-data-length + hex-encoded data. OP_RETURN outputs **must have 0 satoshis** (miners reject non-zero OP_RETURN):

```json
wallet_call({"endpoint": "createAction", "params": {
  "description": "On-chain proof",
  "outputs": [{"lockingScript": "006a...<hex-data>", "satoshis": 0, "outputDescription": "runtime proof", "basket": "worm-runtime-proofs"}],
  "options": {"acceptDelayedBroadcast": false, "randomizeOutputs": false}
}})
```

The locking script format: `00` (OP_FALSE) + `6a` (OP_RETURN) + push opcode + data bytes. For ≤75 bytes, the push opcode is the data length as a single byte (e.g., `24` = 36 bytes, `20` = 32 bytes).

**Basket rule:** Use `worm-runtime-proofs` for user-requested proofs. Never use `worm-proofs` — that basket is reserved for the system's internal audit trail.

### Check Transaction History

```json
wallet_call({"endpoint": "listActions", "params": {"labels": [], "includeOutputs": true, "limit": 10}})
```

### List UTXOs in a Basket

```json
wallet_call({"endpoint": "listOutputs", "params": {"basket": "default", "limit": 25}})
```

## When to Use wallet_call

Use it for endpoints that do NOT have a dedicated tool: discovery, certificates, HMAC, key linkage, deferred transaction signing, and status checks.

## When NOT to Use wallet_call

These dedicated tools exist and have better error handling:

| Task | Use this tool instead |
|------|-----------------------|
| Check balance | `wallet_balance` |
| Get identity/derive key | `wallet_identity` |
| Encrypt/decrypt | `wallet_encrypt` / `wallet_decrypt` |
| Check certificates | `check_certificates` |
| Receive BSV | `receive_address` (discoverable) |
| Internalize payment | `fund_from_tx` (discoverable) |
| Make x402 payment | `x402_call` |

## Endpoint Catalog

### Discovery (FREE / READ-ONLY)

The key use case. Find other agents and their capabilities.

| Endpoint | Purpose | Example params |
|----------|---------|----------------|
| `discoverByIdentityKey` | Find certificates for a known identity | `{"identityKey": "03abc...", "limit": 10}` |
| `discoverByAttributes` | Find identities by certificate attributes | `{"attributes": {"name": "value"}, "limit": 10}` |

Both accept an optional `certificateType` field to filter by type.

**Workflows:**
- "Who is this agent?" -> `discoverByIdentityKey` with their pubkey
- "Find agents with capability X" -> `discoverByAttributes` with `{"capabilities": "X"}`

### Certificate Management (WRITE)

| Endpoint | Purpose | Example params |
|----------|---------|----------------|
| `listCertificates` | List certs by certifier/type | `{"certifiers": ["03..."], "types": ["type-id"], "limit": 10, "offset": 0}` |
| `proveCertificate` | Selective field reveal | `{"certificate": {...}, "fieldsToReveal": ["name", "capabilities"]}` |
| `acquireCertificate` | Acquire a new certificate | `{"type": "...", "certifier": "03...", "subject": "03...", "fields": {...}, "serialNumber": "...", "revocationOutpoint": "...", "signature": "..."}` |
| `relinquishCertificate` | Release a certificate | `{"certificate": {"type": "...", "certifier": "03...", "serialNumber": "..."}}` |

**Workflow — Prove identity to another agent:**
```json
wallet_call({"endpoint": "proveCertificate", "params": {

From Calhooon/dolphinmilk, Apache-2.0.

More from Calhooon/dolphinmilk