Skip to content

api-reference.md

Latest commit

 

History

History
209 lines (145 loc) · 4.35 KB

api-reference.md

File metadata and controls

209 lines (145 loc) · 4.35 KB

API reference

All methods are async and return Promise<T>. All errors extend WraithError.

WraithClient

new WraithClient({
  connection: Connection,        // required
  cluster?: Cluster,             // 'mainnet-beta' (default) | 'devnet' | 'testnet' | 'localnet'
  programId?: PublicKey,         // override program ID
  indexerUrl?: string,           // default 'https://indexer.wraith.dev'
  commitment?: Commitment,       // default 'confirmed'
})

client.ping()

client.ping(): Promise<{ ok: true; version: string; cluster: Cluster }>

Health-check. Returns indexer version on success, throws on network error.

client.agents

register(params)

client.agents.register({
  name: string,
  description?: string,
  scopes: AgentScope[],
  signer: Keypair,
  nonce?: Uint8Array,
}): Promise<Agent>

Throws if scopes is empty or contains a malformed scope string.

get(id)

client.agents.get(id: AgentId): Promise<Agent>

Throws AgentNotFoundError (HTTP 404).

list(opts)

client.agents.list({
  owner?: PublicKey,
  limit?: number,    // 1..200, default 50
  cursor?: string,
}): Promise<{ agents: Agent[]; cursor: string | null }>

update(id, patch, signer)

client.agents.update(id, { name?, description? }, signer): Promise<Agent>

Coming Q2 2026.

transfer(id, newOwner, signer)

client.agents.transfer(id, newOwner: PublicKey, signer): Promise<void>

Coming Q2 2026.

client.bonds

create(params)

client.bonds.create({
  agentId: AgentId,
  amount: number,    // SOL, must be >= 0.1
  signer: Keypair,
}): Promise<Bond>

Throws InsufficientBondError if amount is below the protocol minimum (0.1 SOL). Throws if signer balance is below amount.

get(id), list(opts)

Standard read endpoints.

topUp(id, addAmount, signer) — Q2 2026

withdraw(id, signer) — Q2 2026

client.proofs

submit(params)

client.proofs.submit({
  agentId: AgentId,
  taskId: string,
  commitHash: string,    // 32-byte hex (64 chars)
  signer: Keypair,       // agent's action key, NOT owner's
}): Promise<Proof>

The signer is the agent's dedicated action key, which is different from the owner's wallet. Action keys are derived deterministically from the owner's wallet via BIP32 paths — see Agents docs.

verify(id)

client.proofs.verify(id: ProofId): Promise<boolean>

Returns true only if the signature is valid AND the agent is currently bonded. Throws ProofVerificationError on indexer errors.

client.claims

file(params)

client.claims.file({
  agentId: AgentId,
  bondId: BondId,
  reason: string,           // 16..256 chars
  evidence: ClaimEvidence,
  signer: Keypair,
}): Promise<Claim>

evidence.description is required. txSignature and proofId are optional but strongly recommended — claims without supporting evidence are dismissed by default.

vote(id, verdict, signer)

Validator-only. Throws if signer is not in the active validator set.

resolve(id, signer)

Anyone can call. Triggers on-chain payout for a claim with a settled verdict (review window expired and votes tallied).

client.pricing

estimate({ scopes })

client.pricing.estimate({ scopes }): Promise<PricingEstimate>

Falls back to local computation if the indexer is unreachable.

getRates()

client.pricing.getRates(): Promise<Record<string, number>>

Canonical scope-weight table. Throws on network error (no fallback — if you need this, you need the canonical version).

client.dashboard

Aggregate read endpoints for building dashboards.

client.dashboard.trustScore(agentId): Promise<TrustScoreRecord>
client.dashboard.health():            Promise<BondHealth>
client.dashboard.alerts():            Promise<Alert[]>

Errors

import {
  WraithError,
  AgentNotFoundError,
  InsufficientBondError,
  ClaimRejectedError,
  ProofVerificationError,
} from '@wraith/sdk';

Every error has a name matching the class. Catch the base WraithError to handle anything from the SDK without missing edge cases:

try {
  await client.bonds.create({ ... });
} catch (err) {
  if (err instanceof WraithError) {
    console.error(err.name, err.message);
  } else {
    throw err;
  }
}