credian

Official TypeScript SDK for Credian — banking and trust scoring for AI agents.

npm install credian

Quick Start

For Agent Developers (your agent needs to transact)

import { Credian } from "credian";

const av = new Credian({
  apiKey: process.env.CREDIAN_API_KEY,
});

// Check your balance
const balance = await av.bank.getBalance("av_acc_5t8r2w9y");
console.log(`Available: $${balance.available}`);

// Pay another agent
const payment = await av.bank.pay({
  to: { type: "agent", agentId: "av_agt_3j8w1n5q" },
  amount: 5.0,
  currency: "USD",
  category: "data_purchase",
  memo: "Company enrichment data",
});

// Check a counterparty's trust score before transacting
const score = await av.score.get("av_agt_3j8w1n5q");
if (score.value >= 500) {
  // Safe to do business
}

For Platform Developers (you host agents and want to check trust)

import { Credian } from "credian";

const av = new Credian({
  apiKey: process.env.CREDIAN_PLATFORM_KEY,
});

// Check an agent's score before granting access
const score = await av.score.get("av_agt_7k9x2m4p");

if (score.value < 300) {
  throw new Error("Agent trust score too low");
}

// Report agent behavior (feeds into their score)
await av.events.report("av_agt_7k9x2m4p", [
  {
    type: "task.completed",
    data: { taskId: "task_123", success: true, duration_ms: 4200 },
  },
]);

// Batch check scores for multiple agents
const scores = await av.score.getBatch([
  "av_agt_7k9x2m4p",
  "av_agt_3j8w1n5q",
  "av_agt_9r1s3t5u",
]);

For Owners (you manage agents)

import { Credian } from "credian";

// Owners authenticate with OAuth, not API keys
const av = new Credian({
  accessToken: ownerOAuthToken,
});

// Register a new agent
const agent = await av.agents.register({
  name: "invoice-processor-prod",
  metadata: {
    model: "claude-sonnet-4-5-20250929",
    framework: "langchain",
    capabilities: ["invoice-processing", "payment-initiation"],
  },
});

console.log(`Agent ID: ${agent.agentId}`);
console.log(`SID: ${agent.sid}`);
console.log(`API Key: ${agent.apiKey}`); // Save this — only shown once

// Set spending policy
await av.bank.setPolicy(agent.accountId, {
  maxPerTransaction: 50.0,
  maxDaily: 500.0,
  allowedCategories: ["api_calls", "data_purchase"],
  minimumCounterpartyScore: 300,
  requireHumanApproval: {
    when: "amount > 100",
    approvers: ["[email protected]"],
    timeout: "30m",
    onTimeout: "deny",
  },
});

// Fund the agent's account
await av.bank.fund(agent.accountId, {
  amount: 1000.0,
  currency: "USD",
  source: "funding_source_abc",
});

// Subscribe to score changes
await av.webhooks.create({
  url: "https://acme.com/webhooks/credian",
  events: ["score.changed"],
  filters: { agentIds: [agent.agentId], thresholds: { below: 400 } },
});

API Reference

Client Initialization

import { Credian } from "credian";

// For agents (API key auth)
const av = new Credian({
  apiKey: "av_key_...",
});

// For owners (OAuth auth)
const av = new Credian({
  accessToken: "eyJ...",
});

// With options
const av = new Credian({
  apiKey: "av_key_...",
  baseUrl: "https://api.credian.com", // default
  timeout: 30_000, // ms, default 30s
  retries: 3, // auto-retry on 5xx, default 3
});

av.agents — Agent Management

// Register a new agent (owner auth required)
const agent = await av.agents.register(input: RegisterAgentInput);

// Get agent profile
const agent = await av.agents.get(agentId: string);

// Update agent metadata
const agent = await av.agents.update(agentId: string, input: UpdateAgentInput);

// Deactivate agent (owner auth required)
await av.agents.deactivate(agentId: string);

av.score — Trust Scoring

// Get an agent's current score
const score = await av.score.get(agentId: string);
// Returns: { value, confidence, trend, percentile, breakdown, lastUpdated }

// Get score history
const history = await av.score.getHistory(agentId: string, options?: {
  from?: Date;
  to?: Date;
  limit?: number;
});
// Returns: ScoreSnapshot[]

// Batch lookup (up to 100 agents)
const scores = await av.score.getBatch(agentIds: string[]);
// Returns: Map<string, AgentScore>

av.events — Event Reporting (for platforms)

// Report behavioral events
const result = await av.events.report(agentId: string, events: AgentEvent[]);
// Returns: { accepted: number, rejected: number, errors?: ValidationError[] }

// Get event history
const events = await av.events.list(agentId: string, options?: {
  type?: string;
  from?: Date;
  to?: Date;
  cursor?: string;
  limit?: number;
});

av.credentials — Trust Credentials

// Issue a credential
const cred = await av.credentials.issue({
  agentId: "av_agt_...",
  type: "payment_history",
  claims: { totalTransactions: 342, onTimeRate: 0.97 },
  expiresAt: new Date("2027-06-15"),
});

// Verify a credential
const result = await av.credentials.verify(credentialId: string);
// Returns: { valid: boolean, status, claims, issuedBy, expiresAt }

// Get credential details
const cred = await av.credentials.get(credentialId: string);

// Revoke a credential
await av.credentials.revoke(credentialId: string);

av.bank — Banking Operations

// Get account balance
const balance = await av.bank.getBalance(accountId: string);
// Returns: { available, pending, currency }

// Make a payment
const payment = await av.bank.pay(input: PaymentInput);
// Returns: { paymentId, status, amount, fee, policyCheck, settledAt }

// Batch micropayments
const batch = await av.bank.payBatch(input: BatchPaymentInput);
// Returns: { batchId, status, paymentCount, totalAmount }

// Get transaction history
const txns = await av.bank.getTransactions(accountId: string, options?: {
  from?: Date;
  to?: Date;
  cursor?: string;
  limit?: number;
});

// Set spending policy (owner auth required)
await av.bank.setPolicy(accountId: string, policy: SpendingPolicy);

// Get current policy
const policy = await av.bank.getPolicy(accountId: string);

// Fund account (owner auth required)
await av.bank.fund(accountId: string, input: FundInput);

// Freeze account (kill switch)
await av.bank.freeze(accountId: string);

// Unfreeze account
await av.bank.unfreeze(accountId: string);

av.fleet — Fleet Management (owner auth required)

// Create a fleet
const fleet = await av.fleet.create(input: CreateFleetInput);

// Get fleet summary
const summary = await av.fleet.getSummary(fleetId: string);
// Returns: { totalBudget, totalSpent, agentCount, agents[] }

// Allocate budgets
await av.fleet.allocate(fleetId: string, allocations: Allocation[]);

// Set fleet-wide policy
await av.fleet.setPolicy(fleetId: string, policy: SpendingPolicy);

av.webhooks — Webhook Subscriptions

// Create subscription
const sub = await av.webhooks.create(input: WebhookInput);

// List subscriptions
const subs = await av.webhooks.list();

// Delete subscription
await av.webhooks.delete(subscriptionId: string);

Webhook Signature Verification (utility)

import { verifyWebhookSignature } from "credian";

// In your webhook handler
app.post("/webhooks/credian", (req, res) => {
  const isValid = verifyWebhookSignature(
    req.body,
    req.headers["x-credian-signature"],
    webhookSecret
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;
  // Handle event...
});

Framework Integrations

LangChain Tool

import { CredianTool } from "credian/langchain";

const tools = [
  new CredianTool({
    apiKey: process.env.CREDIAN_API_KEY,
    accountId: "av_acc_5t8r2w9y",
    capabilities: ["pay", "check_balance", "check_score"],
  }),
];

CrewAI Tool

import { CredianCrewTool } from "credian/crewai";

const payment_tool = CredianCrewTool.payment({
  apiKey: process.env.CREDIAN_API_KEY,
  accountId: "av_acc_5t8r2w9y",
});

Vercel AI SDK

import { credianTools } from "credian/ai-sdk";

const tools = credianTools({
  apiKey: process.env.CREDIAN_API_KEY,
  accountId: "av_acc_5t8r2w9y",
});

Error Handling

All errors are typed and include an error code:

import { CredianError } from "credian";

try {
  await av.bank.pay({ ... });
} catch (error) {
  if (error instanceof CredianError) {
    console.error(error.code);     // "POLICY_DENIED"
    console.error(error.message);  // "Payment exceeds daily limit"
    console.error(error.details);  // { limit: 500, attempted: 750 }
    console.error(error.status);   // 403
  }
}

Types

All types are exported:

import type {
  Agent,
  AgentScore,
  ScoreSnapshot,
  AgentEvent,
  Credential,
  PaymentInput,
  PaymentResult,
  SpendingPolicy,
  WebhookEvent,
  CredianError,
} from "credian";

Project Structure

credian-sdk/
├── src/
│   ├── index.ts                     Main export (Credian class)
│   ├── client.ts                    HTTP client (fetch wrapper, retries, auth)
│   ├── resources/
│   │   ├── agents.ts                av.agents.* methods
│   │   ├── scores.ts                av.score.* methods
│   │   ├── events.ts                av.events.* methods
│   │   ├── credentials.ts           av.credentials.* methods
│   │   ├── bank.ts                  av.bank.* methods
│   │   ├── fleet.ts                 av.fleet.* methods
│   │   └── webhooks.ts              av.webhooks.* methods
│   ├── integrations/
│   │   ├── langchain.ts             LangChain tool adapter
│   │   ├── crewai.ts                CrewAI tool adapter
│   │   └── ai-sdk.ts                Vercel AI SDK adapter
│   ├── types/
│   │   ├── agents.ts                Agent types
│   │   ├── scores.ts                Score types
│   │   ├── events.ts                Event types
│   │   ├── credentials.ts           Credential types
│   │   ├── bank.ts                  Banking types
│   │   ├── fleet.ts                 Fleet types
│   │   ├── webhooks.ts              Webhook types
│   │   ├── errors.ts                Error types
│   │   └── common.ts                Shared types (pagination, etc.)
│   ├── webhooks.ts                  Webhook signature verification utility
│   └── errors.ts                    CredianError class
├── tests/
│   ├── client.test.ts
│   ├── resources/
│   │   ├── agents.test.ts
│   │   ├── scores.test.ts
│   │   ├── events.test.ts
│   │   ├── credentials.test.ts
│   │   ├── bank.test.ts
│   │   ├── fleet.test.ts
│   │   └── webhooks.test.ts
│   └── integrations/
│       └── langchain.test.ts
├── examples/
│   ├── basic-agent.ts               Simple agent making payments
│   ├── platform-integration.ts      Platform checking scores
│   ├── owner-setup.ts               Owner registering and configuring agents
│   ├── multi-agent-payments.ts      Agent-to-agent transactions
│   └── langchain-agent.ts           LangChain integration example
├── docs/
│   └── api-reference.md
├── package.json
├── tsconfig.json
├── tsup.config.ts                   Build config (ESM + CJS)
├── .npmignore
└── README.md

Package Details

• Package name: credian
• Exports: ESM and CommonJS (dual package)
• TypeScript: Full type definitions included
• Zero dependencies: Uses native fetch (Node 18+)
• Min Node version: 18.0.0
• License: MIT

Status

Phase: Planning