# HeartBank® APIs

> One site for every HeartBank® API: Log in with HeartBank®, Sign with HeartBank®, Confirm with HeartBank®, Thank with HeartBank®, Look up with HeartBank®, and Verify with HeartBank®. An agent can do everything except the press.

Plain facts, before any endpoint:

- An agent can do everything except the press: every thank and every signature needs the person's own passkey.
- Log in authenticates; Sign attests. A log-in session can never sign.
- A refusal from Thank says nothing (no reason, no count): it protects the people involved, and it is not a bug.
- Outside apps write Thank from season 2 (7 January 2027): Kiitos, and Kiitti only as a person's thanks to all of life.
- Look up with HeartBank® answers one exact name with what its public page shows: never an identity, never a list.
- Verify with HeartBank® is free forever, with no account. A B-Trace℠ lookup through the API is metered; checking a record is free.

## Log in with HeartBank®

Prove who someone is, with a passkey. OpenID Connect on the FAPI 2.0 profile.

- [Reference](https://developers.333.eco/log-in#reference): every operation, generated from openapi/login.json
- [GET https://login.333.eco/.well-known/openid-configuration](https://developers.333.eco/log-in#discovery): The discovery document: every endpoint, scope and algorithm
- [GET https://login.333.eco/.well-known/jwks.json](https://developers.333.eco/log-in#jwks): The keys login signs ID tokens with
- [POST https://login.333.eco/request](https://developers.333.eco/log-in#pushauthorizationrequest): Push the log-in request (PAR, required)
- [GET https://login.333.eco/auth](https://developers.333.eco/log-in#authorize): Send the browser here (one tap from where the person is)
- [POST https://login.333.eco/token](https://developers.333.eco/log-in#token): Exchange the code
- [GET https://login.333.eco/me](https://developers.333.eco/log-in#userinfo): The person's claims
- [POST https://login.333.eco/token/revocation](https://developers.333.eco/log-in#revoke): Revoke a token
- [GET https://login.333.eco/session/end](https://developers.333.eco/log-in#logout): Log out of HeartBank® too
- [GET https://login.333.eco/session/state](https://developers.333.eco/log-in#sessionstate): Is this browser logged in at HeartBank®? (display only)
- [POST https://login.333.eco/notice](https://developers.333.eco/log-in#notice): Announce a security change before making it
- [POST https://login.333.eco/poh](https://developers.333.eco/log-in#verifiedhuman): Read a person's verified-human layers again
- [POST https://login.333.eco/press/wrap](https://developers.333.eco/log-in#wrappress): Thank with HeartBank®: exchange a press for a pressToken

## Sign with HeartBank®

Let the people who use your app sign what they made, and let anyone check it. B-Origin℠.

- [Reference](https://developers.333.eco/sign#reference): every operation, generated from openapi/sign.json
- [POST https://origin.333.eco/api/v1/trace](https://developers.333.eco/sign#trace): Look up what a file carries (B-Trace℠, metered)
- [POST https://sign.333.eco/sign/par](https://developers.333.eco/sign#requestsign): Ask a person to sign a file (from your web page)
- [GET https://sign.333.eco/sign](https://developers.333.eco/sign#signpage): The page where the person signs

## Confirm with HeartBank®

A person's own passkey press for one action your app names: a human in the loop, so you know a person, not a script, did it.

- [Reference](https://developers.333.eco/confirm#reference): every operation, generated from openapi/confirm.json
- [POST https://login.333.eco/confirm/request](https://developers.333.eco/confirm#request): Step 1: ask a person to confirm one action
- [GET https://sign.333.eco/confirm](https://developers.333.eco/confirm#page): Step 2: the page where the person presses
- [POST https://login.333.eco/confirm/redeem](https://developers.333.eco/confirm#redeem): Step 3: redeem the result, once

## Thank with HeartBank®

Record a thank on the gratitude ledger. Your app prepares it, the person presses their own passkey, your app commits it.

- [Reference](https://developers.333.eco/thank#reference): every operation, generated from openapi/thank.json
- [POST https://ledger.heartbank.net/v1/prepare](https://developers.333.eco/thank#prepare): Step 1: prepare a thank
- [POST https://ledger.heartbank.net/v1/commit](https://developers.333.eco/thank#commit): Step 3: commit the pressed thank
- [POST https://ledger.heartbank.net/v1/place](https://developers.333.eco/thank#place): Place one side of a written thank on the public map
- [GET https://ledger.heartbank.net/v1/aura](https://developers.333.eco/thank#ring): Read a person's ring
- [POST https://ledger.heartbank.net/v1/submit](https://developers.333.eco/thank#submit): Retired: a thank without a press (retired)

## Look up with HeartBank®

One exact name on B-Registry℠, and what that person's public page shows. Free, with no key.

- [Reference](https://developers.333.eco/lookup#reference): every operation, generated from openapi/lookup.json
- [GET https://333.eco/api/v1/names/{name}](https://developers.333.eco/lookup#byname): Look up one exact name

## Verify with HeartBank®

Check anything we say, from the public logs, free forever, with no account and no key.

- [Reference](https://developers.333.eco/verify#reference): every operation, generated from openapi/verify.json
- [GET https://log.333.eco/origin/checkpoint](https://developers.333.eco/verify#checkpoint): The latest signed checkpoint: the log's size and root
- [GET https://log.333.eco/origin/checkpoints/{size}](https://developers.333.eco/verify#checkpointat): Every earlier checkpoint, locked (written once, never replaced)
- [GET https://log.333.eco/origin/tile/{level}/{index}](https://developers.333.eco/verify#tile): A tile of the Merkle tree
- [GET https://log.333.eco/origin/tile/entries/{index}](https://developers.333.eco/verify#entries): A bundle of the log's entries
- [GET https://log.333.eco/origin/stamps/index.json](https://developers.333.eco/verify#stampsindex): Which checkpoints carry which clock
- [GET https://log.333.eco/origin/stamps/{size}.{authority}.tsr](https://developers.333.eco/verify#timestamptoken): A timestamp authority's token (RFC 3161) over a checkpoint
- [GET https://log.333.eco/origin/stamps/{size}.ots](https://developers.333.eco/verify#bitcoinproof): An OpenTimestamps proof over a checkpoint, reaching Bitcoin
- [GET https://log.333.eco/ledger/proof/{from}-{to}.json](https://developers.333.eco/verify#zerosumproof): The ledger only: the zero-sum proof over entries from…to

## Optional

- [The MCP server](https://developers.333.eco/agents): its public tools are generated from the same descriptions