Agent Credit Engine

Micro-credit infrastructure for AI agents. Instant USDC loans on Solana and Base with automated repayment.

Agent Credit Engine (ACE) is credit infrastructure for autonomous AI agents. ACE is non-custodial — it never touches your agent's private keys. Agents borrow USDC on Solana and Base, execute revenue-generating tasks, and automatically repay when revenue arrives. ACE supports Solana mainnet and Base mainnet.

No manual loan review required.

Why ACE exists

AI agents are increasingly autonomous — they trade, call APIs, pay for compute. But they face a liquidity problem: they need to spend before they earn. ACE solves this with instant credit evaluated by a 14-signal risk engine, disbursed on-chain in real USDC, with fully automated repayment.

Key features

• 14-signal real-time risk scoring
• On-chain USDC disbursement on Solana and Base
• Automatic wallet polling and revenue detection
• Waterfall repayment engine
• Double-entry ledger with audit trail
• Risk-based fee (typically 3–5%), no monthly costs

Base URL

https://api.agentcreditengine.com

Swagger / OpenAPI

https://api.agentcreditengine.com/docs

For AI Agents

ACE is designed for autonomous software — not humans.

AI agents can:

• Request credit programmatically
• Execute revenue-generating tasks
• Receive USDC payments on-chain
• Automatically repay loans from revenue

All without manual review or human-in-the-loop execution.

If your agent can make an API call, it can use ACE.

Quick Start

Complete integration in under 5 minutes.

1. Install the SDK

npm install @valeo-ace/sdk

2. Initialize the client

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

const ace = new ACE({
  apiKey: "your-api-key",
  baseUrl: "https://api.agentcreditengine.com"
});

3. Register your agent

const agent = await ace.agents.create({
  externalId: "my-trading-bot",
  name: "Trading Bot Alpha"
});

4. Connect a wallet

// Solana wallet
const wallet = await ace.wallets.connect(agent.id, {
  address: "YourSolanaPublicKey...",
  chain: "SOLANA",
  asset: "USDC"
});

// OR Base wallet
const wallet = await ace.wallets.connect(agent.id, {
  address: "0xYourBaseAddress",
  chain: "BASE",
  asset: "USDC"
});

5. Request credit

const credit = await ace.credit.request(agent.id, {
  amount: "15.000000",
  purpose: "DataProvider API call"
});

if (credit.result === "APPROVED") {
  console.log(`Loan: ${credit.loanId}`);
  console.log(`Amount: ${credit.approvedAmount} USDC`);
  console.log(`Fee: ${credit.fee} USDC`);
  console.log(`Due in: ${credit.durationSeconds}s`);
  // USDC is disbursed to the connected wallet automatically
}

Or with raw HTTP

curl -X POST https://api.agentcreditengine.com/api/v1/agents/{agentId}/credit/request \
  -H "X-Api-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":"15.000000","purpose":"DataProvider API call"}'

Building Your Score

Before requesting credit, you can build a credit profile by ingesting past transactions. This is optional but significantly increases your approval chances and credit limit.

// Ingest past transactions to build a credit profile
await ace.transactions.ingest(agent.id, {
  walletId: wallet.id,
  txHash: "SolanaTransactionSignature...",
  direction: "INBOUND",
  amount: "50.000000",
  chain: "SOLANA",
  asset: "USDC"
});

Ingest a mix of inbound and outbound transactions from your wallet's history. More volume and consistent activity produce higher risk scores. The repayment_success_rate signal carries the heaviest weight (200) in the scoring model.

First 24 Hours — Bootstrap Playbook

A brand new agent has zero history and will likely be denied credit. Here's the fastest path to your first successful loan:

Hour 0: Register & Connect

• Register for an API key
• Create your agent
• Connect your Solana or Base wallet

Hour 0–1: Build History

• Ingest 5–10 real past transactions from your wallet
• Mix of inbound and outbound shows healthy activity
• More volume = higher score

Hour 1: First Loan

• Request a small amount (1 USDC)
• Let the disbursement complete
• Send revenue back to the wallet
• ACE auto-repays — your first successful repayment is recorded

Hour 2–12: Build Score

• Repeat 2–3 small loans
• Each successful repayment increases your risk score
• On-time repayments boost the repayment_success_rate signal (200 weight — the heaviest)

Hour 12–24: Scale Up

• Your score should be 500+ after 3 successful repayments
• Request larger amounts
• Your credit limit increases automatically as your score rises

After 24 hours of healthy activity, your agent should be in Tier 2 (score 500–699) with access to standard loan amounts.

Example: AI Agent Buying Market Data

A trading agent needs market signals that cost 2 USDC. The agent only has 0.5 USDC.

1. Agent requests 2 USDC credit from ACE
2. Risk engine scores the agent at 742/1000 → APPROVED
3. ACE disburses 2 USDC to the agent's wallet (Solana or Base)
4. Agent calls DataProvider API, pays 2 USDC
5. Agent receives market signals, executes trades
6. Trades earn 8 USDC — revenue arrives in the agent's wallet
7. ACE wallet monitor detects the 8 USDC inbound transfer
8. Waterfall repayment: 2.06 USDC auto-repaid (2 principal + 0.06 fee)
9. Agent keeps 5.94 USDC profit

Authentication

All API requests require an API key passed in the X-Api-Key header:

curl https://api.agentcreditengine.com/api/v1/agents \
  -H "X-Api-Key: your-api-key"

With the SDK, pass it in the constructor:

const ace = new ACE({ apiKey: "your-api-key" });

Getting an API key

To request an API key, contact the ACE team at team@valeo.dev

Idempotency

All POST requests require an X-Idempotency-Key header. The SDK generates this automatically using crypto.randomUUID(). If you're using the API directly:

curl -X POST https://api.agentcreditengine.com/api/v1/agents \
  -H "X-Api-Key: your-api-key" \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "my-bot", "name": "My Bot"}'

Installation

npm

npm install @valeo-ace/sdk

yarn

yarn add @valeo-ace/sdk

pnpm

pnpm add @valeo-ace/sdk

Requirements

• Node.js 18+ (uses native fetch())
• Also works in browsers, Deno, and Bun
• Zero runtime dependencies

TypeScript

Full type definitions are included. No @types/ package needed.

import { ACE, Agent, CreditDecision, Loan } from "@valeo-ace/sdk";

How ACE Works

The complete credit cycle, from request to repayment:

Architecture

ACE consists of several interconnected components:

• ACE API — RESTful API that agents call to register, request credit, and ingest transactions
• Risk Engine — Scores 14 signals in real-time, producing a 0–1000 risk score
• Treasury — USDC liquidity pools on Solana and Base that fund disbursements
• Wallet Monitor — Polls agent wallets every 60–180 seconds for inbound USDC
• Waterfall Engine — Automatically repays loans from detected revenue (principal first, then fee)
• Double-Entry Ledger — Records every financial operation as balanced debit/credit entries

Credit Lifecycle

A loan moves through these states:

Agent status

A suspended agent's credit line is frozen. Existing loans continue to accrue and can still be repaid, but no new credit is issued.

Loan parameters

Risk Engine

ACE evaluates 14 signals to produce a risk score from 0 to 1000:

Signals are normalized and combined into a weighted risk score from 0–1000. The scoring model adjusts dynamically based on the agent's evolving behavior.

Score thresholds

Hard deny rules

These cause instant rejection regardless of score:

• Kill switch is active
• Agent is suspended
• Credit line is frozen
• Agent age below minimum (default: 1 day)
• Recent failures exceed threshold
• Utilization above 90%
• Requested amount exceeds max single loan policy

Waterfall Repayment

When inbound USDC is detected in an agent's wallet, the waterfall engine distributes it:

1. Principal — repaid first from the oldest active loan
2. Fee — repaid after principal is covered
3. Remaining — stays in the agent's wallet

If the inbound amount doesn't fully cover the loan, a partial repayment is recorded and the loan remains ACTIVE with a reduced outstanding balance.

Multiple active loans are repaid in order: oldest first.

Treasury & Ledger

ACE maintains a double-entry ledger. Every financial operation creates balanced debit/credit entries:

Treasury reconciliation runs every 15 minutes, comparing on-chain balances with the ledger.

Treasury

ACE loans are funded from the ACE treasury — USDC liquidity pools held on Solana mainnet and Base mainnet.

The treasury:

• Holds USDC used to issue short-term micro-credit
• Reconciles on-chain balance vs ledger every 15 minutes
• Enforces hourly and daily disbursement limits
• Maintains a minimum reserve

Future versions

• LP-funded credit pools
• Protocol liquidity providers
• Yield-bearing credit vaults
• Cross-chain treasury (Ethereum)

Supported Assets

Currently ACE supports:

• Solana mainnet — USDC (SPL token)
• Base mainnet — USDC (ERC-20)

Both chains use USDC with 6-decimal precision. Disbursement and repayment work identically on both chains.

Future versions may support additional stablecoins (USDT, DAI) and chains (Ethereum).

Security

ACE implements multiple safeguards to protect funds and prevent abuse:

• Idempotent requests — every POST requires X-Idempotency-Key, preventing duplicate loans
• Circuit breaker — 3 consecutive disbursement failures auto-activates the kill switch
• Treasury reconciliation — on-chain balance checked against ledger every 15 minutes
• Hard deny rules — instant rejection for suspended agents, frozen credit lines, utilization above 90%
• Kill switch — system-wide credit pause, activatable via admin API or automatically
• Double-entry ledger — every financial operation creates balanced debit/credit entries
• Rate limiting — per-IP and per-key limits on all endpoints
• Input validation — Solana and Base address format validation, amount bounds, body size limits
• No secret exposure — treasury keys never logged or returned in API responses

Webhooks & Events

ACE emits webhooks for key lifecycle events. Configure your agent's webhook URL when registering:

Events

Webhook payload

{
  "event": "loan.repaid",
  "loanId": "cmm1ghi...",
  "agentId": "cmm1abc...",
  "amount": "15.450000",
  "timestamp": "2026-03-12T..."
}

Webhook headers

X-ACE-Signature: a3f8c1d2e4b5...
X-ACE-Timestamp: 1710000000

The timestamp can be used to reject stale webhooks and prevent replay attacks.

Webhook Security

Each webhook request includes an HMAC-SHA256 signature in the X-ACE-Signature header, computed using your agent's webhook secret.

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Always verify the signature before processing webhook events.

API Reference — Agents

Create Agent

Request body:

{
  "externalId": "my-trading-bot",
  "name": "Trading Bot Alpha",
  "description": "Automated market maker",
  "webhookUrl": "https://myapp.com/webhooks/ace",
  "metadata": { "version": "2.1" }
}

Response:

{
  "data": {
    "id": "cmm1abc...",
    "externalId": "my-trading-bot",
    "name": "Trading Bot Alpha",
    "status": "ACTIVE",
    "createdAt": "2026-03-12T..."
  }
}

Get Agent

List Agents

Update Agent

{
  "name": "Updated Name",
  "webhookUrl": "https://new-url.com/webhook"
}

API Reference — Wallets

Connect Wallet

Solana wallet:

{
  "address": "69z98b9Zpe58dToP4aouHgi9kMyf6Y3htifdWA2pZQ25",
  "chain": "SOLANA",
  "asset": "USDC",
  "label": "primary"
}

Base (EVM) wallet:

{
  "address": "0x4df375e577825ae021c1b44ba94F8CD84E59750c",
  "chain": "BASE",
  "asset": "USDC",
  "label": "base-primary"
}

List Wallets

API Reference — Credit

Request Credit

{
  "amount": "15.000000",
  "purpose": "DataProvider API call"
}

Response (approved):

{
  "data": {
    "decisionId": "cmm1def...",
    "result": "APPROVED",
    "reasonCodes": ["GOOD_HISTORY", "repaymentSuccessRate_POSITIVE"],
    "approvedAmount": "15.000000",
    "fee": "0.450000",
    "feeRate": "0.030000",
    "totalDue": "15.450000",
    "durationSeconds": 86400,
    "riskScore": "742.500000",
    "loanId": "cmm1ghi..."
  }
}

Response (denied):

{
  "data": {
    "decisionId": "cmm1jkl...",
    "result": "DENIED",
    "reasonCodes": ["KILL_SWITCH_ACTIVE"],
    "expiresAt": null
  }
}

Get Credit Line

Get Credit Profile

API Reference — Loans

Get Loan

{
  "data": {
    "id": "cmm1ghi...",
    "principal": "15.000000",
    "fee": "0.450000",
    "totalDue": "15.450000",
    "totalRepaid": "15.450000",
    "outstandingBalance": "0.000000",
    "status": "REPAID",
    "dueAt": "2026-03-13T...",
    "repaidAt": "2026-03-12T..."
  }
}

List Loans

Get Disbursement Status

{
  "data": {
    "status": "CONFIRMED",
    "txHash": "4Hw3RCEjnP4EGY1kXV8DFr5sNg8dHdZoKwg...",
    "confirmedAt": "2026-03-12T...",
    "error": null
  }
}

API Reference — Transactions

Ingest Transactions

{
  "transactions": [
    {
      "walletId": "cmm1mno...",
      "txHash": "SolanaTransactionSignature...",
      "direction": "INBOUND",
      "amount": "50.000000",
      "chain": "SOLANA",
      "asset": "USDC",
      "counterparty": "SenderAddress...",
      "memo": "Payment for services"
    }
  ]
}

List Transactions

API Reference — Webhooks

Report Revenue (inbound)

{
  "agentId": "cmm1abc...",
  "amount": "50.000000",
  "txHash": "SolanaTransactionSignature...",
  "asset": "USDC",
  "chain": "SOLANA"
}

SDK — Installation & Configuration

npm install @valeo-ace/sdk

Configuration

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

const ace = new ACE({
  apiKey: "your-api-key",          // Required
  baseUrl: "https://api.agentcreditengine.com", // Default
  timeout: 30000,                  // Default: 30s
});

SDK — Usage Examples

Check credit availability before requesting

const profile = await ace.credit.getCreditProfile(agentId);
const line = await ace.credit.getCreditLine(agentId);

console.log(`Risk score: ${profile.riskScore}`);
console.log(`Available credit: ${line.availableCredit} USDC`);

if (parseFloat(line.availableCredit) >= 15) {
  const credit = await ace.credit.request(agentId, {
    amount: "15.000000"
  });
}

Monitor loan status

const loan = await ace.loans.get(loanId);

switch (loan.status) {
  case "ACTIVE":
    console.log(`Due: ${loan.outstandingBalance} USDC by ${loan.dueAt}`);
    break;
  case "REPAID":
    console.log(`Repaid at ${loan.repaidAt}`);
    break;
  case "OVERDUE":
    console.log(`OVERDUE — was due at ${loan.dueAt}`);
    break;
}

Verify on-chain disbursement

const disbursement = await ace.loans.getDisbursement(loanId);

if (disbursement.txHash) {
  console.log(`Verified on-chain: ${disbursement.txHash}`);
  // Solana: https://solscan.io/tx/${disbursement.txHash}
  // Base:   https://basescan.org/tx/${disbursement.txHash}
}

SDK — Error Handling

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

try {
  const credit = await ace.credit.request(agentId, {
    amount: "100"
  });
} catch (err) {
  if (err instanceof ACEAuthError) {
    console.error("Invalid API key");
  } else if (err instanceof ACERateLimitError) {
    console.error("Rate limited — retry after delay");
  } else if (err instanceof ACEError) {
    console.error(`API error: ${err.message} (${err.code})`);
  }
}

Response Envelope

All successful responses wrap data in a data field:

{
  "data": {
    "id": "cmm1abc...",
    "status": "ACTIVE"
  }
}

All error responses use this shape:

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "error": "Bad Request",
  "message": "body/amount must be a positive number"
}

HTTP status codes used:

• 200 — Success
• 201 — Created
• 400 — Validation error
• 401 — Invalid or missing API key
• 404 — Resource not found
• 409 — Conflict (duplicate externalId)
• 429 — Rate limited
• 500 — Internal error

Pricing

ACE charges a risk-based fee per approved loan, typically 3–5%. The fee is deducted from repayment — not charged upfront.

No setup fees. No monthly minimums. No platform subscription.

Fee schedule

Established agents with strong repayment records typically qualify for rates near the 3% base. New agents with limited history start at the higher end.

Example

• Borrow 100 USDC at 3% fee
• Fee: 3 USDC
• Total due: 103 USDC
• Agent earns revenue, 103 USDC auto-repaid
• Agent keeps everything above 103 USDC

Rate Limits

Rate limit headers returned on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1710000000

Limits

Limits can be configured by ACE administrators.

Concepts

• Agent — An autonomous software program registered with ACE. Each agent has a unique externalId, connected wallets, and a credit profile.
• Wallet — A Solana public key or Base (EVM) address connected to an agent. ACE monitors this address for inbound USDC transfers.
• Credit Line — The maximum amount an agent can borrow at any time. Determined by risk score and replenished as loans are repaid.
• Credit Profile — Aggregate statistics about an agent's borrowing history: total borrowed, total repaid, success rate, risk score.
• Loan — A single credit issuance. Has a principal, fee, due date, and status (ACTIVE, REPAID, OVERDUE, DEFAULTED).
• Disbursement — The on-chain USDC transfer from the ACE treasury to the agent's wallet on Solana or Base.
• Repayment — The process of paying back a loan. Happens automatically when the waterfall engine detects sufficient inbound revenue.
• Revenue Detection — ACE polls agent wallets every 60–180 seconds to detect new inbound USDC transfers.
• Waterfall — The repayment priority system: principal first, then fee. Oldest loan repaid first.
• Treasury — The USDC liquidity pools on Solana and Base that fund all agent loans.
• Kill Switch — Emergency system-wide credit pause. Activates automatically after 3 consecutive disbursement failures.

Production Notes

• Use idempotency keys for every POST request — prevents duplicate loans and transactions if a request is retried
• Store webhook secrets securely — treat them like API keys; never commit to source control
• Verify on-chain disbursement before assuming settlement — check the disbursement status endpoint to confirm the transaction was finalized on Solana or Base
• Handle OVERDUE and DEFAULTED states explicitly — your agent should have logic for what happens when a loan cannot be repaid on time
• Monitor rate-limit headers — back off when X-RateLimit-Remaining approaches zero to avoid 429 errors
• Log all credit decisions — store the decisionId and reasonCodes from every credit request for debugging and audit

FAQ

Does ACE have access to my wallet?

No. ACE is non-custodial and never has access to your agent's private keys. It monitors the wallet address for inbound transfers (read-only) and sends USDC to it. The agent maintains full custody.

What happens if revenue never arrives?

The loan enters OVERDUE status after the due date (default: 24 hours). A 72-hour grace period follows. If still unpaid, the loan is marked DEFAULTED and the agent's credit line is frozen.

Can an agent have multiple active loans?

Yes, up to the agent's credit limit. Each new loan reduces available credit. Repayments replenish the credit line automatically.

Is repayment only in USDC?

Yes. ACE only detects and processes USDC transfers on Solana and Base. Other tokens are ignored.

Which chains does ACE support?

ACE operates on Solana mainnet and Base mainnet. Both chains use USDC with 6-decimal precision.

What's the minimum loan amount?

0.10 USDC. Maximum single loan: 10 USDC (configurable by admin).

Support

© 2026 Valeo Technology LLC · Built by Valeo Protocol