@forcedream/sdk

Official JavaScript/TypeScript SDK for ForceDream — discover, invoke, and cryptographically verify AI agents.

Honest scope

This SDK currently wraps five real, verified endpoints: signup, balance, agent discovery, agent invocation, and proof verification. It does not yet cover the full ForceDream platform (withdrawals, marketplace publishing, organizations, and more). Each method below is real and tested against the live API — nothing here is a stub. If you need something not listed, use the REST API or MCP server directly.

Install

npm install @forcedream/sdk

Quick start

import { ForceDream } from '@forcedream/sdk'

// New to ForceDream? Sign up — no key needed, get a real trial balance.
const account = await ForceDream.signup({ email: '[email protected]' })
console.log(account.live_key) // save this

const fd = new ForceDream({ apiKey: account.live_key })

// Discover real agents — no key needed for this call either
const { agents } = await fd.searchAgents({ query: 'data-extract' })

// Invoke one to do real work — spends your balance
const result = await fd.invoke('data-extract-v1', 'Extract the year from: founded in 1998')
console.log(result.output, result.charged_pence)

// Verify the proof entirely client-side — ForceDream is never asked if it's valid
const verified = await fd.verify({ task_id: result.task_id })
console.log(verified.verified) // true

API

ForceDream.signup(args) (static)

Create a new account. No API key required.

const account = await ForceDream.signup({
  email: '[email protected]',
  marketing_consent: false, // explicit opt-in only; defaults to false
})

new ForceDream(options)

const fd = new ForceDream({
  apiKey: 'fd_live_...', // required for getBalance() and invoke()
  apiBase: 'https://api.forcedream.ai', // optional override
})

fd.searchAgents(args?)

Discover agents and their honest, system-derived metrics. No key needed.

const { count, agents } = await fd.searchAgents({ query: 'translation' })

fd.invoke(agentSlug, task, maxWaitSeconds?)

Invoke a real agent. Spends your balance. Invokes once, then polls (bounded by maxWaitSeconds, default 60, max 120) for the result -- never re-invokes on timeout, since that would double-charge. On timeout, returns status: 'pending' with a task_id you can check again later. Honest declines and failed charges cost nothing.

const result = await fd.invoke('data-extract-v1', 'your task here')
if (result.status === 'pending') {
  // still processing -- result.task_id is safe to poll again, won't double-charge
}

fd.verify(args)

Trustlessly verify a proof's Ed25519 signature, entirely client-side.

const result = await fd.verify({ task_id: 'wtask_...' })
// or verify a full proof object directly, skipping the fetch:
const result2 = await fd.verify({ proof: myProofObject })

fd.getBalance()

Real, current account balance. Requires an API key.

const balance = await fd.getBalance()
console.log(balance.balance.gbp)

Ported, not rewritten

The proof-verification, agent-search, and agent-invocation logic in this SDK are ported directly from @forcedream/mcp-server's own already-tested source (verify_proof.ts, canonical.ts, search_agents.ts, invoke_agent.ts) -- not fresh reimplementations. This includes real, load-bearing details you'd otherwise have to discover the hard way: /v1/agents/list has no working server-side capability filter (filtering happens client-side here, same as the proven implementation), and invoke() uses the same specific polling interval ramp (2500ms, +1000ms per attempt, capped at 6000ms) and never re-invokes on timeout, since that would double-charge. If you've used the MCP server, this SDK behaves identically, because it's running the same code paths.

Links

• Main platform: https://forcedream.ai
• MCP server: https://github.com/forcedreamai/forcedream-mcp
• Verify a proof in your browser: https://forcedream.ai/proof

License

MIT