@candledottv/agent-sdk 0.6.9 → 0.6.11

package/README.md

@@ -37,6 +37,7 @@ const candle = new CandleClient({
 const market = await candle.getMarket("solana", "So11...mint")
 const quote = await candle.getQuote("solana", "So11...mint", { side: "buy", amountIn: "1000000000" })
 const feed = await candle.getFeed("new", "solana")
+const card = await candle.getTokenCard("solana", "So11...mint")
 const events = await candle.getTokenEvents("solana", "So11...mint", { kind: "signal", since: "2026-10-28T00:00:00Z" })
 const verdict = await candle.verify("hood", "0xToken")
 
@@ -49,10 +50,76 @@ const request = candle.expandPreset(presets, "solana-open-sol", {
 })
 ```
 
-The API key is attached as `x-api-key` on every request when configured. The keyed methods
+The API key is attached as `x-api-key` when configured, except on public `tokenPages` reads. The keyed methods
 (`launch`, `launchAsync`, `dryRunLaunch`, `getLaunchJob`, `reportActivity`, `uploadImage`)
 refuse to fetch without one and throw a plain `Error` locally instead of a server 401.
 
+## Token page About (unreleased source)
+
+`candle.tokenPages` reads About and immutable section history, and submits claims, section edits,
+restores, flags and immutable updates. These methods need a human-owned SDK release before they are available in the
+published package. Token page switches default off; a server can return `404` or `feature_off`.
+
+| Method | Access | Result |
+| --- | --- | --- |
+| `about(token)` | Public, no key sent | `TokenAbout`, with public feature switches |
+| `burns(token, { cursor, limit })` | Public, CNDL only | `AboutBurnHistory` |
+| `history(token, section, { cursor, limit })` | Public, no key sent | `AboutHistory`, including tombstones |
+| `capabilities(token)` | `token-pages:read` | Private `AboutCapabilities` |
+| `creatorChallenge(token)` | `token-pages:write` | Exact message, challenge ID and expiry |
+| `claim(token, body, options)` | `token-pages:write` | Claim result and idempotency key |
+| `setSection(token, section, body, options)` | `token-pages:write` | New version ID/revision and idempotency key |
+| `restoreSection(token, section, body, options)` | `token-pages:write` | New version ID/revision and idempotency key |
+| `updates(token, { cursor, limit })` | Public, no key sent | `AboutUpdates`, newest first with tombstones |
+| `postUpdate(token, { text }, options)` | `token-pages:write`, current 0.5% | Immutable post ID/sequence and idempotency key |
+| `deletePost(token, id, options)` | `token-pages:write`, author account | Soft delete, including after selling |
+| `seen(token)` | `token-pages:read` | Own `AboutSeen` unread position |
+| `markSeen(token, visibleUpdateSequence, options)` | `token-pages:write` | Monotonic seen result and idempotency key; call after rendering visible updates |
+| `flag(token, body, options)` | `token-pages:write` | Flag result and idempotency key |
+
+The token is `{ chain: "solana" | "hood", address: string }`; sections are `thesis`, `tokenomics`
+and `lore`. History and burn pagination accepts a returned opaque cursor and a limit from 1 to 50.
+Revisions and raw amounts remain strings. Reads bypass caches; capabilities are never folded into
+public About. Hidden/removed history bodies stay null. The API validates strict bodies, text limits,
+fresh eligibility and restrictions on every write. Existing keys gain no scope automatically.
+Claim/edit/restore require 0.5% of current supply; any positive eligible balance can flag.
+
+```ts
+const token = { chain: "solana" as const, address: mint }
+const about = await candle.tokenPages.about(token)
+const capabilities = await candle.tokenPages.capabilities(token)
+// Persist this key and the draft before sending; a rerun must reuse both.
+const idempotencyKey = crypto.randomUUID()
+if (about.features.edit && capabilities.canEdit) {
+  const saved = await candle.tokenPages.setSection(token, "thesis", {
+    text: "Our thesis",
+    baseRevision: about.sections.thesis?.revision ?? "0",
+  }, { idempotencyKey })
+  console.log(saved.data.revision, saved.idempotencyKey)
+}
+```
+
+Claim explicitly with `{ kind: "holder" }` or `{ kind: "creator", challengeId?, signature? }`.
+A known creator may need no additional signature. Otherwise call `creatorChallenge`, sign the exact
+UTF-8 message locally and pass its challenge ID and signature in a separate creator claim. Solana
+signatures use base64; Hood uses the 65-byte `0x` message signature. No method signs, creates a
+transaction, requests a private key, implicitly claims or automatically restores on conflict.
+Challenges are attempted once and expire after five minutes.
+
+Restore takes `{ versionId, baseRevision }` and appends a new version; it never rewrites history.
+Flag takes `{ contentId, reason, detail? }` for an exact version, with reason `spam`, `scam`, `abuse`,
+`misleading`, `unsafe_link` or `other`. Restoring a removed/unsafe version is refused.
+
+Every content write sends `Idempotency-Key` from `options.idempotencyKey` or a generated UUID and
+returns `{ data, idempotencyKey }`. A connection or interrupted-body failure retries once with the
+same key and serialized body. HTTP refusals are not retried. `TokenPageError` extends `CandleApiError`:
+branch on `code` and `status`, retain `idempotencyKey`, inspect `latest` for `revision_conflict`, and
+respect `retryAfterHeader` on rate limits. Two missing answers or an invalid success produce
+`OUTCOME_UNKNOWN`; explicitly replay the same request/key to recover its result. A conflict leaves
+the caller's draft untouched. Feature-off, missing scope/auth, insufficient holding, expired/replayed
+proof, unsafe text, unavailable eligibility and old-server errors remain refusals for the caller to
+handle. Do not log content bodies, credentials or creator signatures.
+
 ## Embedded launches with built-in idempotent retries
 
 `launch()` fills in a `clientLaunchId` (`"sdk-" + crypto.randomUUID()`) when you omit one, and

package/dist/client.d.ts

@@ -15,7 +15,7 @@
  *   payload (`getQuotePairs`, `getPresets`, `getMarket`, `getLaunchJob`, `getAgentProfile`)
  *   return the useful inner object; methods whose top-level body IS the useful object
  *   (`launch`, `dryRunLaunch`, `getQuote`, `getFeed`, `verify`) return the parsed body.
- * - `x-api-key` is attached to EVERY request when the client has a key. The write/keyed
+ * - `x-api-key` is attached when the client has a key, except on public tokenPages reads. The write/keyed
  *   endpoints (launch, dry run, jobs, activity, uploads) refuse to fetch at all without one,
  *   throwing a plain `Error` that names the missing option, so a misconfigured agent fails
  *   fast and locally instead of with a server 401.
@@ -50,6 +50,7 @@ import { type PerpsFillsPage, type PerpsFundingPage, type PerpsHistoryOptions }
 import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
 import type { SecretStore } from "./secret-store";
 import type { CandleStaking } from "./staking";
+import { type ClusterResult } from "./token-clusters";
 import { type WalletChain } from "./wallet-import";
 export type Chain = "solana" | "hood";
 /**
@@ -494,6 +495,7 @@ export interface TokenEventGroup {
     visibility: TokenEventGroupVisibility;
 }
 export interface TokenEventWallet {
+    /** Display text (first4…last4) for free/keyless reads; full address for Pro/Max keys. */
     address: string;
     name: string | null;
     walletKind: "dev" | "kol" | "smart" | "agent" | "tracked";
@@ -539,6 +541,203 @@ export interface TokenEventsPage {
     events: TokenEvent[];
     nextCursor: string | null;
 }
+/**
+ * One hacc card fact (BE-2117 `/v1/tokens/:mint/card-facts`, carried whole by the card route).
+ * `state: "ok"` has a `value`, `source`, `as_of` and `basis`; anything else has `value: null` and
+ * `display: "–"`. A percent fact's `value` is 0 to 100.
+ */
+export interface TokenCardFact {
+    value: number | null;
+    display: string;
+    state: "ok" | "pending" | "unavailable";
+    source: string | null;
+    as_of: string | null;
+    basis: string | null;
+    note: string | null;
+}
+/** A same-name candidate: another token on a venue whose ticker or name matches. */
+export interface TokenCardSameNameCandidate {
+    mint: string;
+    chain: Chain;
+    ticker: string | null;
+    name: string | null;
+    venue: string | null;
+    market_cap_usd: number | null;
+    liquidity_usd: number | null;
+    pair_created_at: string | null;
+    match: "ticker" | "name" | "both" | "self";
+    found_by: "dexscreener" | "hacc" | "both";
+}
+/** hacc's same-name block: which same-name token leads on live market cap, then liquidity. */
+export interface TokenCardSameName {
+    state: "found" | "none" | "unavailable";
+    source: string;
+    display: string;
+    leader: TokenCardSameNameCandidate | null;
+    subject: (TokenCardSameNameCandidate & {
+        rank: number | null;
+    }) | null;
+    trailing: boolean | null;
+    others: TokenCardSameNameCandidate[];
+    detail: string | null;
+}
+/** hacc's card facts for one token, as `GET /v1/tokens/:mint/card-facts` answers them (BE-2117). */
+export interface TokenCardFacts {
+    mint: string;
+    chain: Chain;
+    as_of: string;
+    cache_s: number;
+    fields: Record<"bundles" | "snipers" | "insiders" | "fresh_1d" | "fresh_7d" | "avg_wallet_age", TokenCardFact>;
+    launch: {
+        state: "ok" | "pending" | "failed" | "not_read";
+        source: string | null;
+        computed_at: string | null;
+        deployer: string | null;
+        first_buy_at: string | null;
+        rows_read: number | null;
+        covered_s: number | null;
+        truncated: boolean | null;
+        detail: string | null;
+    };
+    holders: {
+        source: string | null;
+        sampled: number;
+        known_age: number;
+        detail: string | null;
+    };
+    same_name: TokenCardSameName;
+    ath: {
+        source: string;
+        stored_usd: number | null;
+        stored_at: string | null;
+        usable_usd: number | null;
+        check: "confirmed" | "unconfirmed" | "over_ceiling" | "below_live" | "unverifiable" | "none";
+    };
+    vendor_reads: Record<"dexscreener" | "helius" | "cvc" | "blockscout" | "birdeye" | "other", number>;
+    cached: boolean;
+}
+/**
+ * GET /api/v1/tokens/:chain/:mint/card (BE-2118): the data behind a token card, the same for every
+ * caller and every plan. Facts only, never a score. A field with no source is `null` (show an en
+ * dash), and `sources` names where each block came from.
+ */
+/**
+ * Creator metadata edit (BE-2140): the four links Candle keeps for a token. In an edit, a string
+ * sets a link and `""` or `null` removes it; a key left out is unchanged.
+ */
+export type TokenMetadataSocialKey = "website" | "twitter" | "telegram" | "discord";
+export type TokenMetadataSocials = Partial<Record<TokenMetadataSocialKey, string>>;
+export interface EditTokenMetadataRequest {
+    chain: Chain;
+    mint: string;
+    /** Replaces the description; `""` clears it. At most 500 characters, safe for on-chain JSON. */
+    description?: string;
+    /** Any subset of the four links; each at most 200 characters, an absolute http(s) URL. */
+    socials?: Partial<Record<TokenMetadataSocialKey, string | null>>;
+}
+/** `PATCH /api/v1/tokens/:chain/:mint/metadata`'s payload: the token's state after the edit. */
+export interface TokenMetadataEditResult {
+    chain: Chain;
+    mint: string;
+    /** False when the edit re-sent the current values; no version was added. */
+    changed: boolean;
+    /** The newest edit version, or null when the token has never been edited. */
+    version: number | null;
+    description: string;
+    socials: TokenMetadataSocials;
+    /** Always `candle` today: the edit is Candle's copy, nothing is written on chain. */
+    chainState: "candle" | "onchain" | "pending" | "failed" | "superseded";
+    chainTx: string | null;
+}
+export interface TokenMetadataHistoryItem {
+    version: number;
+    createdAt: string;
+    /** `description` and `socials.<key>`. */
+    changedFields: string[];
+    description: string;
+    socials: TokenMetadataSocials;
+    prevDescription: string;
+    prevSocials: TokenMetadataSocials;
+    chainState: TokenMetadataEditResult["chainState"];
+    chainTx: string | null;
+    /** The published agent's name, or null for the neutral "Agent". Never an account or key. */
+    author: {
+        kind: "agent";
+        name: string | null;
+    };
+}
+export interface TokenMetadataHistory {
+    chain: Chain;
+    mint: string;
+    /** Newest first. */
+    items: TokenMetadataHistoryItem[];
+    /** Pass as `cursor` for the next page; null on the last. */
+    nextCursor: string | null;
+}
+export interface TokenCard {
+    chain: Chain;
+    mint: string;
+    generatedAt: number;
+    identity: {
+        name: string | null;
+        symbol: string | null;
+        launchpad: string | null;
+        isCandle: boolean | null;
+    };
+    market: {
+        priceUsd: number | null;
+        marketCapUsd: number | null;
+        liquidityUsd: number | null;
+        change5mPct: number | null;
+        volume5mUsd: number | null;
+        buys5m: number | null;
+        sells5m: number | null;
+        updatedAt: number | null;
+    };
+    /** The highest daily price since launch times current supply; null when no source covers it. */
+    ath: {
+        marketCapUsd: number;
+        at: number;
+        precision: "day";
+        basis: "price times current supply (FDV)";
+    } | null;
+    /** The forensics route's report, or why there is none (`not_covered` carries its coverage). */
+    forensics: {
+        state: "ok";
+        report: unknown;
+    } | {
+        state: "not_covered";
+        coverage: unknown;
+    } | {
+        state: "unavailable";
+    };
+    /** Tracked-wallet trades, signals and callouts in the last hour, at the free tier. */
+    events: {
+        state: "ok";
+        windowMinutes: 60;
+        trackedBuys: number;
+        trackedSells: number;
+        signals: number;
+        callouts: number;
+        names: string[];
+    } | {
+        state: "off" | "unavailable";
+    };
+    hacc: {
+        state: "ok";
+        facts: TokenCardFacts;
+    } | {
+        state: "off" | "unavailable";
+    };
+    sameName: TokenCardSameName | {
+        state: "off" | "unavailable";
+    };
+    sources: Record<"identity" | "market" | "ath" | "forensics" | "events" | "sameName" | "hacc", string>;
+    /** Candle's token page, carrying the card source tag when one was given. */
+    links: {
+        token: string;
+    };
+}
 /** GET /api/v1/markets/:chain/:mint, unwrapped from `{ success, market }`. */
 export interface MarketState {
     /** Additive Release A fields are optional when connected to an older API. */
@@ -746,6 +945,11 @@ export interface AgentProfile {
     username: string | null;
     launches: number;
     launchesViaApi: number;
+    /**
+     * Billing tier. Private: present only when the request is authenticated as this account (its own
+     * agent key); absent for any other caller.
+     */
+    tier?: "free" | "believer" | "pro" | "max";
 }
 /** Claimed fee income on public board entries and records. Older snapshots omit these fields. */
 export interface AgentFeeIncome {
@@ -3076,6 +3280,8 @@ export declare class CrossOriginRedirectError extends Error {
  */
 export declare function keyedRedirectGuard(doFetch: typeof fetch): typeof fetch;
 export declare class CandleClient {
+    /** About reads and scoped writes. No implicit signing, claiming or conflict resolution. */
+    readonly tokenPages: import("./token-pages").CandleTokenPages;
     private readonly apiUrl;
     private readonly apiKey?;
     private readonly fetchImpl;
@@ -3136,7 +3342,49 @@ export declare class CandleClient {
         limit?: number;
         before?: string;
     }): Promise<TokenEventsPage>;
+    /**
+     * The token card for one token (`GET /api/v1/tokens/:chain/:mint/card`): market, the all-time
+     * high since launch, forensics coverage, hacc's safety and same-name facts, and tracked wallets
+     * in the last hour. Free for every plan and the same for every caller; no key is needed. `tag`
+     * is a card source tag (`v1.<group>.<poster>.<card>`) carried on `links.token` for counting card
+     * arrivals; it credits nobody, and the route ignores a malformed one. The route is off until the
+     * deployment sets `TOKEN_CARD_ENABLED` on; off it answers 503 `TOKEN_CARD_DISABLED`.
+     */
+    getTokenCard(chain: Chain, mint: string, opts?: {
+        tag?: string;
+    }): Promise<TokenCard>;
+    /**
+     * Edit Candle's copy of a token's description and links, as the token's creator
+     * (`PATCH /api/v1/tokens/:chain/:mint/metadata`, BE-2140). Needs a key with `launch:write` whose
+     * account launched the token. Name, symbol and image cannot be changed, and nothing is written
+     * on chain: Candle's page and API change, wallets reading on-chain metadata do not. A Hood token
+     * that carries its metadata on chain is refused (`ONCHAIN_METADATA_TOKEN`), as is a TEE-launched
+     * Hood token (`TEE_LAUNCHED_HOOD_TOKEN`). Every call sends an Idempotency-Key (a fresh one unless
+     * `idempotencyKey` is given); retrying with the same key and request returns the first result and
+     * never edits twice. Off until the deployment sets `TOKEN_METADATA_EDIT_ENABLED`; off it answers
+     * 503 `METADATA_EDIT_DISABLED`.
+     */
+    editTokenMetadata(request: EditTokenMetadataRequest, opts?: {
+        idempotencyKey?: string;
+    }): Promise<TokenMetadataEditResult>;
+    /** A token's metadata edits, newest first (`GET .../metadata/history`). Public; no key is needed. */
+    tokenMetadataHistory(params: {
+        chain: Chain;
+        mint: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<TokenMetadataHistory>;
     verify(chain: Chain, mint: string): Promise<VerifyResult>;
+    /**
+     * BE-2006: optional third-party cluster analysis for a Solana token. Resolves the same
+     * `ClusterResult` union as the API and `candle token clusters`, and never throws for an
+     * unavailable analysis: unavailable is a normal result with a `reason`, not zero clustered supply.
+     * A request that fails, times out or returns an unusable body resolves reason `transport_error`.
+     * One request, no retry, no key sent, nothing cached here. Hood resolves `unsupported_chain`.
+     */
+    getTokenClusters(mint: string, opts?: {
+        chain?: Chain;
+    }): Promise<ClusterResult>;
     getOwnProfile(): Promise<OwnAgentProfile>;
     updateOwnProfile(patch: OwnAgentProfilePatch): Promise<{
         success: true;
@@ -4158,7 +4406,7 @@ export declare function __setEvmReceiptWaitForTest(opts: {
     pollMs?: number;
 } | null): void;
 /** This build's own version. Kept in lockstep with package.json by the release-bump CI guard. */
-export declare const SDK_VERSION = "0.6.9";
+export declare const SDK_VERSION = "0.6.11";
 /** Test seam: the once-per-process latch would otherwise weld the suite's first case to the rest. */
 export declare function __resetSdkUpdateNoticeForTest(): void;
 //# sourceMappingURL=client.d.ts.map