Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Screenshots live in `docs/images/` and are linked with relative Markdown image s
An image appears once its change is merged to `main`.
Use PNG or WebP under 250 KB, crop to the relevant component, and write descriptive alt text.
Public screenshots must not show test funds, local-fork labels, chain ids of test networks,
test accounts or internal organization names.
test accounts or internal project names.

Changes go through a pull request with a passing **Docs check** before merging. A second
person's approval is not required, so a solo maintainer can merge their own checked PR.
Expand Down
2 changes: 1 addition & 1 deletion docs/api/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Enable **API**, **MCP** or both, choose only the needed read scopes and select a
Copy the secret when it appears; Claire retains a hash, not a recoverable copy. Revoke it when no longer needed. Changing its methods or scopes requires explicit manager approval and does not rotate the secret or expiry.
:::

![The Create key dialog: a name, an access method of API, MCP or Both, read permissions for organization context, Knowledge, asset metadata, Telegram, X mentions and token, and a 7-, 30- or 90-day expiry.](../images/developer-create-key.webp)
![The Create key dialog: a name, an access method of API, MCP or Both, read permissions for project context, Knowledge, asset metadata, Telegram, X mentions and token, and a 7-, 30- or 90-day expiry.](../images/developer-create-key.webp)

> [!WARNING]
> Store the key in your server environment or agent's secret store, never in browser code, a public variable, a skill file or source control. A key stops working if its issuer loses owner or admin membership.
Expand Down
6 changes: 3 additions & 3 deletions docs/api/claire-proof.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ order: 46

## Read the Claire Proof

`GET /api/v1/token/proof` (MCP tool `get_token_proof`, scope `token:read`) returns the [Claire Proof](../sources/token-actions/claire-proof.md) for the organization's linked token, the facts its public proof page shows plus the detail behind them, with `data` set to `null` when no token is linked. Unlike the other token reads it makes RPC requests: the on-chain figures come from one read at one block, stated in `block`, and are cached briefly. It returns:
`GET /api/v1/token/proof` (MCP tool `get_token_proof`, scope `token:read`) returns the [Claire Proof](../sources/token-actions/claire-proof.md) for the project's linked token, the facts its public proof page shows plus the detail behind them, with `data` set to `null` when no token is linked. Unlike the other token reads it makes RPC requests: the on-chain figures come from one read at one block, stated in `block`, and are cached briefly. It returns:

- `chainId`, `network`, `explorer`, `url` (the token's permalink `/proof/<chainId>/<token>`, the token's public proof page; append `/badge.svg` for the badge), `token` (`address`, `name`, `symbol`, `decimals`, `totalSupply`) and `block` (`number`, `time`).
- `claire`: whether the token's launch is registered by a Claire router factory (launched or migrated), and `launch` when it is (`router`, `launchpad`, `creator`, `payee`, `payeeKind` of `creator`, `vault`, `split` or `other`, `holderBps`, `buyback`, `pendingPayee` and `migrated`). `payee` and `holderBps` are the current values. `launch.pendingPayee` is `null` or `{ address, kind, effectiveAt }`, the payee change the creator has announced and the time it can take effect. `launch.migrated` is `null` for a token launched through Claire; for a token brought over with `adopt` it holds `at` (ISO time of the adoption block, or `null` if it could not be read) and `block`. A linked token that never migrated is not registered.
- `locked`: raw amounts held by the time, revenue and price lock contracts for this token (`time`, `revenue`, `price`, `total`), `percent` of total supply (`null` when supply is zero), and the organization's published `locks` with their proof URLs. Vested but unclaimed tokens are included.
- `locked`: raw amounts held by the time, revenue and price lock contracts for this token (`time`, `revenue`, `price`, `total`), `percent` of total supply (`null` when supply is zero), and the project's published `locks` with their proof URLs. Vested but unclaimed tokens are included.
- `openingLock` (from the confirmed launch receipt, or `null`), `ponsLocked` (the supply pons' locker holds), `revenue` (the distributor, per asset what the router counted as `routed` and the cumulative total `published` to holders, and the confirmed `rounds` with `evidence` and `manifestUrl`) and `feeRecipient` (the launchpad's creator-fee recipient, `ok` when it is the Claire router, and any `pending` change).
- `contracts` (the lock and proof-view contracts it read) and `links` (the X account and Telegram chat the organization connected inside Claire, which are not on-chain facts). Take verification addresses from `@tryclaire/sdk/protocol`, not from this response.
- `contracts` (the lock and proof-view contracts it read) and `links` (the X account and Telegram chat the project connected inside Claire, which are not on-chain facts). Take verification addresses from `@tryclaire/sdk/protocol`, not from this response.

```sh
curl --header "Authorization: Bearer $CLAIRE_API_KEY" "$CLAIRE_API_URL/token/proof"
Expand Down
2 changes: 1 addition & 1 deletion docs/api/context-and-search.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ curl --get --header "Authorization: Bearer $CLAIRE_API_KEY" \

## Endpoints

`GET /api/v1/context` includes the credential's organization ID and approved sources permitted by their matching read scopes; organization identity fields and connection blocks may be absent when their sources are filtered. `GET /api/v1/sources` lists approved, included sources with matching read scopes, status and timestamps. `GET /api/v1/search` accepts `q`, `source` (an ID from `/sources`), `after`, `before` and `limit` (maximum 50). Search results intersect `context:read` with the per-source read scopes; `context:read` alone does not expose Documents or Notes. Timestamps may include UTC offsets; `after` is inclusive and `before` is exclusive. `data.items` contain bounded previews and source IDs; `data.sources` describes permitted sources and `data.hasMore` indicates additional results or a bounded source pool, **not** complete provider history. Follow source links or scoped detail endpoints for evidence.
`GET /api/v1/context` includes the credential's project ID and approved sources permitted by their matching read scopes; project identity fields and connection blocks may be absent when their sources are filtered. `GET /api/v1/sources` lists approved, included sources with matching read scopes, status and timestamps. `GET /api/v1/search` accepts `q`, `source` (an ID from `/sources`), `after`, `before` and `limit` (maximum 50). Search results intersect `context:read` with the per-source read scopes; `context:read` alone does not expose Documents or Notes. Timestamps may include UTC offsets; `after` is inclusive and `before` is exclusive. `data.items` contain bounded previews and source IDs; `data.sources` describes permitted sources and `data.hasMore` indicates additional results or a bounded source pool, **not** complete provider history. Follow source links or scoped detail endpoints for evidence.
2 changes: 1 addition & 1 deletion docs/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Sources, context and bounded persisted search.
::card[People and other reads]{href=people-and-other-reads.md icon=users}
People, Knowledge, Assets, Telegram, X and token reads.
::card[Token locks, routers and rounds]{href=token-reads.md icon=chart}
The organization's persisted Claire locks, fee routers and rounds.
The project's persisted Claire locks, fee routers and rounds.
::card[Claire Proof endpoint]{href=claire-proof.md icon=shield}
The public proof facts read from the chain at one block.
::card[Freshness and rate limits]{href=errors-and-rate-limits.md icon=bolt}
Expand Down
2 changes: 1 addition & 1 deletion docs/api/scopes.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ In **Knowledge**, the source must also be used (**Claire uses**) **and** explici
| `assets:read` | File and folder metadata, not private object keys, file content or signed URLs. |
| `telegram:read` | Linked chats, stored messages and Telegram-sourced People. |
| `x:read` | Stored mentions and X-sourced People. |
| `token:read` | Stored token identity and observations, plus the organization's Claire locks, fee routers, distribution rounds and the token's Claire Proof. |
| `token:read` | Stored token identity and observations, plus the project's Claire locks, fee routers, distribution rounds and the token's Claire Proof. |

## Next steps

Expand Down
10 changes: 5 additions & 5 deletions docs/api/token-reads.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Token locks, routers and rounds
description: Read the organization's persisted Claire locks, fee routers and distribution rounds.
description: Read the project's persisted Claire locks, fee routers and distribution rounds.
icon: chart
order: 45
---
Expand All @@ -9,13 +9,13 @@ order: 45

## Read token locks, fee routers and rounds

Three read-only endpoints need `token:read` and the organization's approved token source. Each makes no RPC request and returns what Claire persisted from confirmed transactions. They are also MCP tools with the same scope; see [MCP](../mcp/index.md). A fourth, [`token/proof`](claire-proof.md#read-the-claire-proof), does read the chain.
Three read-only endpoints need `token:read` and the project's approved token source. Each makes no RPC request and returns what Claire persisted from confirmed transactions. They are also MCP tools with the same scope; see [MCP](../mcp/index.md). A fourth, [`token/proof`](claire-proof.md#read-the-claire-proof), does read the chain.

| Endpoint | MCP tool | Returns |
| --- | --- | --- |
| `GET /api/v1/token/locks` | `list_token_locks` | The organization's locks from confirmed funding receipts: `kind` (`time`, `revenue` or `price`), `chainId`, lock `contract` and `lockId`, `token`, `funder`, `beneficiary`, raw `amount`, `cancelable`, `cancelNotice`, `transferable`, `fundingTransactionHash`, `published` and a public `id`. Time locks add `schedule` (`timelock`, `linear` or `catch-up-cliff`), `start`, `cliff` and `end`, and `cancelNotice` (seconds the funder must wait between requesting and executing a cancellation; `0` cancels at once; `null` unless the lock is cancelable). For revenue and price locks those time fields are `null`. `revenue` (revenue locks) holds `router`, `asset` (the quote asset; the zero address is native ETH), `baseline`, `deadline` (Unix seconds) and `tranches` (`revenue` threshold in raw units and `bps`). `price` (price locks) holds `router`, `asset`, `highWaterAtCreation`, `deadline` and `tranches` (`price` target in raw quote units per whole token, and `bps`). `proofUrl` is set once the lock is published. Claimed and remaining amounts are on the proof page. |
| `GET /api/v1/token/fee-routers` | `list_fee_routers` | The organization's confirmed fee routers: `router`, `factory`, `launchpad`, `creator` (the launcher), `payee` (who receives the creator share now; the creator can change it with 7 days' notice), `payeeKind` (`creator`, `vault` or `split`), `payeeTerms` (a vault's beneficiary and schedule, or a split's payees and basis points; `null` when the creator is the payee), `buyback` (pons only; `null` when unknown), `holderBps` (the current holder share; the creator can only raise it), `pendingPayee` (a proposed payee, or `null`), `payeeChangeAt` (ISO time the proposal can take effect, or `null`), `payeeChanges` (the history of changes this app confirmed: `type` of `holder_share_raised`, `payee_change_proposed`, `payee_change_canceled` or `payee_changed`, `at`, `transactionHash`, and `from`, `to`, `payee` or `effectiveAt` as relevant), `projectHolderDistributor`, `claireHolderDistributor`, `treasury`, `launchedToken`, and `totals` per asset (the sums of confirmed harvests, in raw units of that asset: `harvests`, `received`, `revenue`, `creator`, `projectHolders`, `claireHolders`, `treasury`). With buyback on, the launch token appears in `totals` as an asset next to the quote. |
| `GET /api/v1/token/rounds` | `list_token_rounds` | The organization's confirmed project-holder and airdrop rounds, 20 per page (`page`): `purpose`, `distributor`, `roundId`, `asset`, `total` (what this round added), `cumulativeTotal` (everything promised for the asset so far), `previousEvidence`, `recipients` (accounts this round added to), `accounts` (accounts with an entitlement in this root), `snapshotBlock`, `root`, `evidence`, `transactionHash`, `manifestUrl` and `publishedAt`. |
| `GET /api/v1/token/locks` | `list_token_locks` | The project's locks from confirmed funding receipts: `kind` (`time`, `revenue` or `price`), `chainId`, lock `contract` and `lockId`, `token`, `funder`, `beneficiary`, raw `amount`, `cancelable`, `cancelNotice`, `transferable`, `fundingTransactionHash`, `published` and a public `id`. Time locks add `schedule` (`timelock`, `linear` or `catch-up-cliff`), `start`, `cliff` and `end`, and `cancelNotice` (seconds the funder must wait between requesting and executing a cancellation; `0` cancels at once; `null` unless the lock is cancelable). For revenue and price locks those time fields are `null`. `revenue` (revenue locks) holds `router`, `asset` (the quote asset; the zero address is native ETH), `baseline`, `deadline` (Unix seconds) and `tranches` (`revenue` threshold in raw units and `bps`). `price` (price locks) holds `router`, `asset`, `highWaterAtCreation`, `deadline` and `tranches` (`price` target in raw quote units per whole token, and `bps`). `proofUrl` is set once the lock is published. Claimed and remaining amounts are on the proof page. |
| `GET /api/v1/token/fee-routers` | `list_fee_routers` | The project's confirmed fee routers: `router`, `factory`, `launchpad`, `creator` (the launcher), `payee` (who receives the creator share now; the creator can change it with 7 days' notice), `payeeKind` (`creator`, `vault` or `split`), `payeeTerms` (a vault's beneficiary and schedule, or a split's payees and basis points; `null` when the creator is the payee), `buyback` (pons only; `null` when unknown), `holderBps` (the current holder share; the creator can only raise it), `pendingPayee` (a proposed payee, or `null`), `payeeChangeAt` (ISO time the proposal can take effect, or `null`), `payeeChanges` (the history of changes this app confirmed: `type` of `holder_share_raised`, `payee_change_proposed`, `payee_change_canceled` or `payee_changed`, `at`, `transactionHash`, and `from`, `to`, `payee` or `effectiveAt` as relevant), `projectHolderDistributor`, `claireHolderDistributor`, `treasury`, `launchedToken`, and `totals` per asset (the sums of confirmed harvests, in raw units of that asset: `harvests`, `received`, `revenue`, `creator`, `projectHolders`, `claireHolders`, `treasury`). With buyback on, the launch token appears in `totals` as an asset next to the quote. |
| `GET /api/v1/token/rounds` | `list_token_rounds` | The project's confirmed project-holder and airdrop rounds, 20 per page (`page`): `purpose`, `distributor`, `roundId`, `asset`, `total` (what this round added), `cumulativeTotal` (everything promised for the asset so far), `previousEvidence`, `recipients` (accounts this round added to), `accounts` (accounts with an entitlement in this root), `snapshotBlock`, `root`, `evidence`, `transactionHash`, `manifestUrl` and `publishedAt`. |

These fields come from receipts Claire confirmed; a change made directly on-chain outside Claire shows in the Claire Proof, which reads the chain. Each fee router also carries `migrated` (true when the router adopted a token launched on pons outside Claire) and `migration`, which is `null` for a router that launched its token itself or has not adopted one. Otherwise it holds `adoptedAt`, `migrationFee` and `migrationFeeToken` (the one-time fee in raw units of its stablecoin), `treasury` and `claireHolders` (the two halves), `historicalPayouts` (per `asset`, the `amount` the router paid the creator uncharged from before the migration) and `transactionHash`.

Expand Down
2 changes: 1 addition & 1 deletion docs/automations/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,4 @@ At delivery, Claire rechecks the rule, approving manager's role, connected accou
> [!IMPORTANT]
> Unknown is never retried automatically. Check the chat before taking another action.

A completed post is not posted again just because pinning it failed. Live delivery has an organization-wide hourly cap; see [current limits](../reference/limits.md). See also [notifications](reports-and-notifications.md).
A completed post is not posted again just because pinning it failed. Live delivery has a project-wide hourly cap; see [current limits](../reference/limits.md). See also [notifications](reports-and-notifications.md).
8 changes: 4 additions & 4 deletions docs/claire/earning.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ order: 31
| --- | --- | --- |
| [Fee rounds](#fee-rounds) | Every holder, pro rata | Cumulative rounds, claimed by you or anyone |
| [Launch airdrops](#launch-airdrops) | Holders of a project's chosen snapshot | A project's own token, until its claims close |
| [Referral rewards](#referral-rewards) | Referrers of paying organizations | Treasury-funded rounds, to your payout wallet |
| [Referral rewards](#referral-rewards) | Referrers of paying projects | Treasury-funded rounds, to your payout wallet |

## Fee rounds

Expand Down Expand Up @@ -63,9 +63,9 @@ The public proof at `/airdrops/<id>` shows the rule, snapshot block, Merkle root

## Referral rewards

Your invite link on the personal **Referrals** page counts link opens (unverified), sign-ups and paying projects separately. An organization keeps the referrer of the account that created it.
Your invite link on the personal **Referrals** page counts link opens (unverified), sign-ups and paying projects separately. A project keeps the referrer of the account that created it.

When such an organization pays a Claire service fee or a Pro plan payment that confirms on-chain, you receive **5% of Claire's treasury share** of that payment, or **7.5%** if your verified holding qualifies when the reward is recorded:
When such a project pays a Claire service fee or a Pro plan payment that confirms on-chain, you receive **5% of Claire's treasury share** of that payment, or **7.5%** if your verified holding qualifies when the reward is recorded:

| Payment | Claire treasury share | Reward at 5% | Reward at 7.5% |
| --- | --- | --- | --- |
Expand All @@ -74,7 +74,7 @@ When such an organization pays a Claire service fee or a Pro plan payment that c
| Pro plan, USD 49 | 49 | 2.45 | 3.675 |

- A reward is never a share of trading revenue, of the $CLAIRE holder half or of project-holder funds.
- Self-referrals are void: there is no reward when you belong to the paying organization, made the payment yourself, or paid from one of your verified wallets. If a payment is reorganized off the chain and confirms again, this is checked again.
- Self-referrals are void: there is no reward when you belong to the paying project, made the payment yourself, or paid from one of your verified wallets. If a payment is reorganized off the chain and confirms again, this is checked again.
- A reward becomes payable once the payment's block is finalized. Claire's treasury then funds payable rewards in a claim round on the fee's chain, in the fee's stablecoin (USDG on Robinhood Chain). Funding a round is not a payout: the reward reaches your payout wallet when a claim is submitted, by you or anyone. A reward waits while you have no verified payout wallet.
- Pro payments are referral payments like service fees; the whole amount is treasury share, so the reward is 5% or 7.5% of USD 49 on the chain it was paid on.

Expand Down
Loading
Loading