@valeo/ace-sdk

TypeScript SDK for Agent Credit Engine — micro-credit infrastructure for AI agents.

Zero dependencies. Works in Node 18+, browsers, Deno, and Bun.

Install

npm install @valeo/ace-sdk

Quick Start

import { ACE } from "@valeo/ace-sdk";

const ace = new ACE({ apiKey: "vak_xxx" });

const agent = await ace.agents.create({ externalId: "trading-bot", name: "Trading Bot" });
const wallet = await ace.wallets.connect(agent.id, { address: "So1ana...", chain: "SOLANA" });
const credit = await ace.credit.request(agent.id, { amount: "15.000000" });

if (credit.result === "APPROVED") {
  console.log(`Loan ${credit.loanId} approved for ${credit.approvedAmount} USDC`);
}

Configuration

const ace = new ACE({
  apiKey: "vak_xxx",                                    // required
  baseUrl: "https://api.agentcreditengine.com",         // default
  timeout: 30000,                                       // ms, default
});

API Reference

Agents

// Create an agent (returns agent with initial credit line and profile)
const agent = await ace.agents.create({
  externalId: "my-bot",
  name: "My Bot",
  description: "Optional description",
  webhookUrl: "https://example.com/webhook",
  metadata: { tier: "premium" },
});

// Get an agent by ID
const agent = await ace.agents.get("agent-id");

// List agents
const { data, pagination } = await ace.agents.list({ page: 1, pageSize: 25 });

// Update an agent
const updated = await ace.agents.update("agent-id", { name: "New Name" });

Wallets

// Connect a Solana wallet
const wallet = await ace.wallets.connect("agent-id", {
  address: "So1anaPublicKey...",
  chain: "SOLANA",
  asset: "USDC",
  label: "Primary Wallet",
});

// List wallets for an agent
const wallets = await ace.wallets.list("agent-id");

Credit

// Request credit
const decision = await ace.credit.request("agent-id", {
  amount: "50.000000",
  purpose: "API call funding",
});

if (decision.result === "APPROVED") {
  console.log(`Approved: ${decision.approvedAmount} USDC`);
  console.log(`Fee: ${decision.fee} (${decision.feeRate})`);
  console.log(`Loan ID: ${decision.loanId}`);
  console.log(`Due in ${decision.durationSeconds}s`);
}

// Get a specific credit decision
const decision = await ace.credit.getDecision("decision-id");

// List credit decisions for an agent
const { data } = await ace.credit.listDecisions("agent-id", { page: 1 });

// Get credit line
const creditLine = await ace.credit.getCreditLine("agent-id");
console.log(`Available: ${creditLine.availableCredit} / ${creditLine.totalLimit}`);

// Get credit profile
const profile = await ace.credit.getCreditProfile("agent-id");
console.log(`Risk score: ${profile.riskScore}`);

Loans

// Get a loan
const loan = await ace.loans.get("loan-id");

// List loans (with optional filters)
const { data } = await ace.loans.list({
  agentId: "agent-id",
  status: "ACTIVE",
  page: 1,
  pageSize: 10,
});

// Make a repayment
const repayment = await ace.loans.repay("loan-id", {
  amount: "25.000000",
});

// Check disbursement status (on-chain USDC transfer)
const disbursement = await ace.loans.getDisbursement("loan-id");
console.log(`Status: ${disbursement.status}, TX: ${disbursement.txHash}`);

// List repayments for a loan
const { data: repayments } = await ace.loans.listRepayments("loan-id");

Transactions

// Ingest a single transaction
await ace.transactions.ingest("agent-id", {
  walletId: "wallet-id",
  txHash: "SolanaTransactionHash...",
  direction: "INBOUND",
  amount: "100.000000",
  chain: "SOLANA",
});

// Ingest multiple transactions at once
await ace.transactions.ingest("agent-id", [
  { walletId: "w1", direction: "INBOUND", amount: "50.00", chain: "SOLANA" },
  { walletId: "w1", direction: "OUTBOUND", amount: "10.00", chain: "SOLANA" },
]);

// List transactions for an agent
const { data } = await ace.transactions.list("agent-id", {
  direction: "INBOUND",
  page: 1,
  pageSize: 50,
});

Webhooks

// Report revenue (triggers automatic loan repayment)
const result = await ace.webhooks.reportRevenue({
  agentId: "agent-id",
  walletAddress: "So1ana...",
  txHash: "optional-tx-hash",
  amount: "75.000000",
  chain: "SOLANA",
});

// Report escrow release
const release = await ace.webhooks.reportEscrowRelease({
  agentId: "agent-id",
  txHash: "escrow-tx-hash",
  amount: "100.000000",
  chain: "SOLANA",
});
console.log(`Captured: ${release.capturedAmount}, Repayments: ${release.repaymentsCount}`);

Error Handling

All API errors throw typed error classes:

import { ACE, ACEError, ACEAuthError, ACEValidationError } from "@valeo/ace-sdk";

const ace = new ACE({ apiKey: "vak_xxx" });

try {
  await ace.agents.create({ externalId: "bot-1", name: "Bot" });
} catch (err) {
  if (err instanceof ACEAuthError) {
    console.error("Invalid API key");
  } else if (err instanceof ACEValidationError) {
    console.error("Validation failed:", err.details);
  } else if (err instanceof ACEError) {
    console.error(`API error ${err.statusCode}: ${err.message}`);
  }
}

| Error Class | Status | When | |---|---|---| | ACEValidationError | 400 | Invalid request body or params | | ACEAuthError | 401 | Missing or invalid API key | | ACENotFoundError | 404 | Resource not found | | ACEConflictError | 409 | Duplicate resource | | ACERateLimitError | 429 | Rate limit exceeded | | ACETimeoutError | — | Request timed out | | ACEError | any | All other API errors |

Idempotency

All POST requests automatically include an X-Idempotency-Key header (generated via crypto.randomUUID()). This prevents duplicate operations if a request is retried.

Links

• Agent Credit Engine
• GitHub