Introduction

WelcomeServices map

Guides

AcceptSpend

Legal

SecurityPrivacyTerms
PreviousWalletsNextSellers & resources
BlogPrivacyTerms

Handles

Your org slug is the pay address for background ledger transfers. Signing in creates one. You can rename it.

Same flow in MCP: rill_claim_handle

Auth

POST /handles/claim and PATCH /handles require an owner Supabase JWT. Resolve and bare-handle lookup are public reads, no key required.

Authorization: Bearer <owner JWT>

Featured endpoints

Set or change the org slug

POST /handles/claim

Creates the account wallet if needed and assigns a generated org slug. Pass handle to set or rename it. The slug is the prefix for agent FQDNs such as research.acme.userill.com.

ParameterTypeRequiredDescription
handlestringnoOptional org slug (letters, numbers, hyphen). Omit to keep the generated slug.

Request body

body
{
  "handle": "acme"
}

What to save

Save account_wallet_id for fund-checkout and mint. The org slug is your pay address and FQDN prefix.

  • MCP twin: rill_claim_handle. PATCH /handles also renames.

Resolve a destination

GET /handles/resolve/:destination

Confirm a destination exists before a background ledger transfer with POST /pay to=…. Accepts @handle, handle FQDN, or agent FQDN. Open-world Spend with pay-url usually targets an HTTPS gate URL instead, so resolve is optional on that path.

ParameterTypeRequiredDescription
destinationpathyes@handle, handle FQDN, or agent FQDN

What to save

Use the resolved handle / agent identity when composing POST /pay transfers.

  • MCP twin: rill_resolve_handle.

All endpoints

  • POST/handles/claimCreate wallet + set or keep org slug
  • PATCH/handlesRename the current org slug
  • GET/handles/resolve/:destination@handle, handle FQDN, or agent FQDN
  • GET/handles/:handleBare handle lookup
  • GET/directoryList pay URLs (rail, payment_ready, max_probe_age_hours, probe_method)
  • POST/directory/syncOwner: refresh catalogs + probe all pay URLs

Usage notes

  • Agent discovery also exposes GET /agent/capabilities.
  • Resolve before background ledger POST /pay transfers; skip resolve for open-world POST /spend/pay-url against HTTPS gates.