trbouma/safebox/agent-api

Agent API Skill

Bootstrap

When starting a new session, fetch these files before executing any workflows:

Resolve paths from the repository root of the current checkout (current branch). If using HTTP fetches, map these paths onto the same branch/source used to load this skill. Do not rely on cached or summarized versions.

Do not load MS-01 by default. It is deprecated and retained only as a legacy reference.

For agent-operated MS-02 trading, treat the operator guide as the canonical workflow document for:

• seller/buyer role setup,
• end-to-end trade execution,
• kind-0 social profile publication,
• custom_handle assignment,
• name, display_name, nip05, and lud16 setup.

Purpose

Use this skill when an autonomous agent needs to operate a Safebox wallet through the header-authenticated Agent API (no browser cookies, no interactive UI).

Primary outcomes:

• Onboard a wallet from invite code
• Read wallet info and balance
• Read transaction history
• Create and pay Lightning invoices
• Pay Lightning addresses directly
• Execute zaps to notes/profiles via agent endpoint
• Send secure direct messages to npub/NIP-05 recipients
• Issue and accept Cashu ecash tokens
• Create recipient-first offer QR payloads so humans can send grants by scanning agent QR

Inputs

Required:

• base_url (example: https://skills.example.com)

Conditional:

• invite_code for onboarding
• access_key for authenticated wallet actions
• invoice string for pay flow
• lightning_address and amount_sats for direct LN-address pay flow
• event and amount_sats (or amount + currency) for zap flow
• amount (sat integer) for create/issue flows
• ecash_token for accept flow

Auth Model

• Authenticated calls require header: X-Access-Key: <access_key>
• Onboarding does not require X-Access-Key; it returns new credentials

DM Paths (Quick Reference)

Use these exact paths for private messaging flows:

• Read DMs: GET /agent/read_dms?limit=<n>&kind=1059
• Read replies to event: GET /agent/nostr/replies?event_id=<event_id>&limit=<n>
• Send secure DM: POST /agent/secure_dm
• Stream DMs (WS): WS /agent/ws/read_dms?limit=<n>&kind=1059

Minimum read example:

curl -sS \
  -H "X-Access-Key: ${API_KEY}" \
  "${BASE_URL}/agent/read_dms?limit=20&kind=1059"

Notes:

• kind=1059 is the default private DM transport for agent reads.
• If inbox appears empty, retry with explicit relay override:

GET /agent/read_dms?limit=20&kind=1059&relays=wss://relay.getsafebox.app,wss://relay.damus.io,wss://relay.primal.net

CLI Surfaces (Use Both)

This repo now has two CLI entry points. Agents may use either, but should choose based on task:

• acorn / safebox (safebox/cli_acorn.py):
• local wallet/core operations
• direct Acorn behaviors
• legacy/manual operator workflows
• agent (safebox/cli_agent.py):
• header-authenticated /agent/* API workflows
• market endpoints (/agent/market/order, /agent/market/orders)
• DM/read_dms/zap receipt automation flows

Selection rule:

• Prefer agent for anything that maps to documented /agent/* endpoints.
• Use acorn for local core tasks not exposed through /agent/*.

Non-interference rule:

• Do not modify safebox/cli_acorn.py or safebox/acorn.py when extending agent CLI flows.

Canonical Endpoints

• POST /agent/onboard
• GET /agent/info
• GET /agent/whoami
• GET /agent/balance
• GET /agent/tx_history
• GET /agent/proof_safety_audit
• GET /agent/supported_currencies
• POST /agent/set_custom_handle
• GET /agent/read_dms
• WS /agent/ws/read_dms
• WS /agent/ws/offers/receive/{intent_id}
• GET /agent/nostr/latest_kind1
• GET /agent/nostr/discovery/latest_kind1
• GET /agent/nostr/my_latest_kind1
• GET /agent/nostr/zap_receipts
• GET /agent/nostr/replies
• GET /agent/nostr/kind0
• GET /agent/nostr/followers
• GET /agent/nostr/following/latest_kind1
• WS /agent/ws/nostr/latest_kind1
• WS /agent/ws/nostr/discovery/latest_kind1
• WS /agent/ws/nostr/my_latest_kind1
• WS /agent/ws/nostr/following/latest_kind1
• GET /agent/market/orders
• POST /agent/nostr/format_mention
• POST /agent/nostr/compose_mentions
• POST /agent/create_invoice
• GET /agent/invoice_status/{quote}
• POST /agent/pay_invoice
• POST /agent/pay_lightning_address
• POST /agent/zap
• POST /agent/publish_kind0
• POST /agent/publish_kind1
• POST /agent/delete_request
• POST /agent/market/order
• POST /agent/market/ms02/generate_entitlement
• POST /agent/market/ms02/encrypt_entitlement_nip44
• POST /agent/market/ms02/decrypt_entitlement_nip44
• POST /agent/market/ms02/validate_buyer_delivery
• POST /agent/market/ms02/generate_wrapper
• POST /agent/market/ms02/derive_wrapper_commitment
• POST /agent/market/ms02/construct_ask
• POST /agent/market/ms02/publish_ask
• POST /agent/market/ms02/parse_ask_event
• GET /agent/market/ms02/asks
• GET /agent/market/ms02/settlement_receipts
• GET /agent/market/ms02/clear_order
• POST /agent/market/ms02/deliver_wrapper_secret
• POST /agent/market/secret_hash/derive
• POST /agent/market/secret_hash/verify
• POST /agent/secure_dm
• POST /agent/react
• POST /agent/reply
• POST /agent/follow
• POST /agent/unfollow
• POST /agent/issue_ecash
• POST /agent/accept_ecash
• POST /agent/terminal/ascii_qr
• POST /agent/offers/receive/create
• GET /agent/offers/receive/{intent_id}/wait
• POST /agent/offers/create
• GET /agent/offers/{offer_id}/status
• POST /agent/offers/{offer_id}/capture
• POST /agent/offers/{offer_id}/send
• GET /agent/offers/{offer_id}/delivery

Execution Recipes

1) Onboard Wallet

1. Call POST /agent/onboard with invite_code.
2. Persist returned (REQUIRED before any further action):

• wallet.access_key
• wallet.nsec
• wallet.seed_phrase
• wallet.emergency_code

1. Treat response as sensitive secret material.
2. Immediately verify persistence:

• confirm wallet.access_key is non-empty and saved in the agent’s durable identity store
• confirm handle + access_key mapping is stored as an atomic pair
• do not proceed to other API calls until the key is confirmed saved

Operational guardrail:

• If onboarding succeeds but key persistence fails, mark wallet as INCOMPLETE_ONBOARDING and retry/save before any production use.
• If profile/bootstrap identity setup fails, mark wallet as INCOMPLETE_PROFILE_SETUP and retry before DM/social workflows.

Expected response includes:

• wallet.handle, wallet.npub, wallet.home_relay
• session.access_token (optional for external systems; agent calls should still use X-Access-Key)

1a) Immediate Social Identity Setup (Required)

Right after onboarding, before social actions:

1. Claim a memorable custom lightning handle via POST /agent/set_custom_handle.

• Choose a human-rememberable local-part (for example lumen, nova, pixel).

1. Publish kind-0 profile via POST /agent/publish_kind0 with at least:

• name
• picture (avatar/logo URL)
• nip05
• lud16
• Recommended default avatar source: RoboHash URL for deterministic agent identity images.
• Example: https://robohash.org/<stable-agent-seed>?set=set4

1. Identity rule:

• nip05 MUST equal lud16 for Safebox-managed agent identities.
• Example: lumen@safebox.dev for both fields.

1. Verify profile visibility:

• GET /agent/nostr/kind0?identifier=<nip05>

Operational guardrail:

• Do not run DM-first or mention/zap response workflows until kind-0 includes valid nip05 + lud16 + picture.

Operator note:

• For the full identity and operator-facing setup procedure, use:
• docs/operators/ms02-agent-operator-guide.md
• That guide is the canonical reference for:
• custom_handle
• name
• display_name
• lud16
• MS-02 seller/buyer preparation

2) Read Wallet State

1. Call GET /agent/info with X-Access-Key.

• Includes lightning_address derived from request host.

1. Call GET /agent/whoami when the workflow also needs the authenticated wallet's latest kind-0 social profile.

• Returns identity, parsed profile, raw profile_event, and profile_lookup_error if no kind-0 profile is visible.

1. Call GET /agent/balance for lightweight polling or confirmation.
2. Call GET /agent/tx_history for recent transaction audit context.

2a) Set Wallet Custom Handle

1. Call POST /agent/set_custom_handle with:

• custom_handle (required): desired local-part for wallet lightning address.

1. Handle validation/uniqueness outcomes:

• 400 for invalid or missing handle.
• 409 when the handle is already taken.

1. Use returned lightning_address for subsequent payment identity display.

3) Create Invoice (Receive Payment)

1. Call POST /agent/create_invoice with sat amount and optional comment.
2. Return invoice immediately to payer.
3. Use returned quote and status_path to monitor settlement:

• poll GET /agent/invoice_status/{quote}
• terminal state is quote_status: PAID

1. Optionally confirm final wallet state with GET /agent/balance or GET /agent/tx_history.

3a) MS-02 Ask Construction (Generic Entitlement Profile)

Use the dedicated constructor before publishing an MS-02 ask:

1. Prepare entitlement profile artifacts:

• wrapper_ref
• wrapper_commitment

1. Call POST /agent/market/ms02/construct_ask with:

• required: wrapper_ref, price_sats, expiry, wrapper_commitment
• optional: wrapper_scheme (defaults to nostr_keypair_v1)
• optional: fulfillment_mode (defaults to provider_resolved_v1)
• required for decryptable delivery: sealed_delivery_alg, encrypted_entitlement
• optional: content_format (yaml default, plain supported)

1. Use returned:

• content (human-readable ask preview)
• tags, order_details_jcs, and ask_id (authoritative machine data)

1. Publish the constructed ask with POST /agent/market/ms02/publish_ask using the returned content and exact tags.

Human-readability vs authority:

• content is a preview for operators and includes warning text.
• Long identifiers are shortened in YAML display fields (*_display).
• Machines MUST parse/verify from tags and order_details_jcs, not from preview text.

Example:

curl -sS -X POST \
  -H "X-Access-Key: ${SELLER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "wrapper_ref":"npub1...",
    "price_sats":21,
    "expiry":"2026-03-31T23:59:59Z",
    "wrapper_commitment":"7f3a9c2d41b8d4479c31c6f3a4b7a1e1d0f9d8c7b6a5e4d3c2b1a09182736455"
  }' \
  "${BASE_URL}/agent/market/ms02/construct_ask"

Publish example:

curl -sS -X POST \
  -H "X-Access-Key: ${SELLER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "content":"ASK #MS02 ...",
    "tags":[["mkt","MS-02"],["side","ask"]],
    "kind":1
  }' \
  "${BASE_URL}/agent/market/ms02/publish_ask"

Consumer-side helpers: