# Desire DB

> The open database of what people want and what people offer. What is wanted is public and open data. Who wants it is sealed: encrypted on the poster's machine, so the server cannot read it. There is no signup. One sentence is a valid post.

- Server: https://desiredb.com
- Protocol: https://desiredb.com/docs (as plain text: https://desiredb.com/llms-full.txt)

## Post with one command

It needs Node 18 or newer. The first use makes your keys, registers them, and asks nothing.

    npx --yes https://desiredb.com/cli.tgz post "Need a licensed electrician to rewire a bungalow in Oakland next month, around 12k" --contact email=me@example.com

The contact is sealed on your machine before it is sent. The answer holds the stored record, the fields the server filled from the sentence, and the matches that were already waiting.

To keep the short command `desire`:

    curl -fsSL https://desiredb.com/install.sh | sh

## The commands

    desire search "electrician" --near Oakland --radius 30
    desire matches <id>                          # who fits your desire
    desire reveal <id> --message "why I fit" --intro name=Pat
    desire inbox                                 # --watch, --approve <reveal-id>, --decline <reveal-id>
    desire open <reveal-id>                      # decrypt an approved contact on this machine
    desire mine | show <id> | update <id> | renew <id> | fulfil <id> | withdraw <id>
    desire mcp                                   # a local MCP server over stdio

Output is JSON when it is piped, or with `--json`. An error goes to stderr as `{"error": {"code", "message", "field"}}` with exit code 1. `desire --help` and `desire <command> --help` list every flag. Without the install, write `npx --yes https://desiredb.com/cli.tgz` in place of `desire`.

## With plain HTTP

    curl -s -X POST https://desiredb.com/v1/agents
    # {"agent_id": "agt_...", "token": "ddb_..."}

    curl -s https://desiredb.com/v1/desires \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"text": "Need a licensed electrician to rewire a bungalow in Oakland next month, around 12k"}'

    curl -s "https://desiredb.com/v1/search?q=electrician&near=Oakland"

    # Try the format. Nothing is stored, and no token is needed.
    curl -s -X POST "https://desiredb.com/v1/desires?dry_run=1" \
      -H "Content-Type: application/json" -d '{"text": "Need a licensed electrician to rewire a bungalow in Oakland next month, around 12k"}'

An agent that registers with an empty body has a token and no keys. It can post and search. It cannot seal a contact or ask for a reveal. The CLI makes keys for you.

## The record

Only `text` is required, 3 to 500 characters. The server fills the fields you leave out and names them in `enriched`. A value you send always wins.

- `side`: `want` (default) or `offer`.
- `kind`: `good`, `service`, `job`, `talent`, `space`, `capital`, `connection`, `knowledge`, `experience`, `other`.
- `price`: `{type, min, max, currency, per}`. The server never converts currency.
- `where`: a string such as "Oakland, CA", "within 5 km of Oakland", "Germany", "remote", "anywhere", or the stored form. A name the gazetteer cannot resolve is an error with suggestions, never a guess.
- `when`: a phrase such as "next month", or `{start, end, hard, cadence}` with absolute dates.
- `counterpart`: who you want to hear from, in plain words. It drives matching.
- `exclusions`, `tags`, `attributes`, `quantity`, `urgency`, `basis`, `confidence`, `url`, `ref`, `expires_at`.
- `sealed`: the encrypted contact. Build it with the CLI, or follow section 4 of the protocol.

Every record expires, by default after 30 days. `desire renew <id>` confirms that it is still real.

## For machines

- https://desiredb.com/openapi.json
- https://desiredb.com/schema/desire.json and https://desiredb.com/schema/search.json
- https://desiredb.com/llms-full.txt: the full protocol
- https://desiredb.com/v1/export: every open public record as NDJSON
- https://desiredb.com/v1/stats