# AgentCredit

> Instant microloans ($1-$5 USDC) for AI agents on Base mainnet. No KYC, no accounts — just your wallet.

- [Full API Documentation](/llms-full.txt): Complete endpoint reference
- [Facilitator discovery](/supported): Supported x402 schemes and networks

## What AgentCredit Does

AgentCredit gives your AI agent **instant access to USDC liquidity** on Base. Need USDC to pay for an API, cover a transaction, or fund any on-chain operation? Request a flash microloan and receive $1-$5 USDC in your wallet within seconds.

**Two ways to use it:**

1. **As an x402 facilitator** — Set AgentCredit as your facilitator URL. When you're short on USDC for an x402 payment, credit is extended automatically during settlement. Zero code changes.

2. **As a standalone lending API** — Call `POST /loans/request` or use the `request_loan` MCP tool anytime your agent needs USDC for **any purpose** — not just x402 payments. Use the loan for API calls, on-chain operations, paying other agents, or anything else.

## Quick Start

### Option A: x402 Facilitator (automatic credit)

```typescript
import { wrapFetch } from '@x402/fetch';
const fetchWith402 = wrapFetch(fetch, walletClient, {
  facilitatorUrl: 'https://agentlending.spekn.com',
});
// First 100 settlements free. Register before the 101st.
```

### Option B: Direct Loan API (any purpose)

All write endpoints require an **EIP-191 signature** proving wallet ownership. Use server-issued nonces for replay protection.

```typescript
import { Wallet } from 'ethers';

const wallet = new Wallet('0xYOUR_PRIVATE_KEY');
const BASE = 'https://agentlending.spekn.com';

// Helper: fetch a single-use nonce (expires in 5 min)
async function getNonce(action: string) {
  const res = await fetch(`${BASE}/auth/nonce?wallet=${wallet.address}&action=${action}`);
  return (await res.json()).nonce;
}

// 1. Register — sign: "AgentCredit:register:<wallet>:<nonce>"
const regNonce = await getNonce('register');
const regMsg = `AgentCredit:register:${wallet.address.toLowerCase()}:${regNonce}`;
const regSig = await wallet.signMessage(regMsg);
await fetch(`${BASE}/agents/register`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet: wallet.address, signature: regSig, nonce: regNonce }),
});

// 2. Request a loan — sign: "AgentCredit:request_loan:<wallet>:<amount>:<nonce>"
const amount = 2.0;
const loanNonce = await getNonce('request_loan');
const loanMsg = `AgentCredit:request_loan:${wallet.address.toLowerCase()}:${amount}:${loanNonce}`;
const loanSig = await wallet.signMessage(loanMsg);
await fetch(`${BASE}/loans/request`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet: wallet.address, amountUsdc: amount, signature: loanSig, nonce: loanNonce }),
});

// 3. Repay via x402 (no signature needed — returns 402)
await fetchWith402('https://agentlending.spekn.com/loans/YOUR_LOAN_ID/pay');
```

### Option C: MCP Tools

```json
{
  "mcpServers": {
    "agentcredit": {
      "type": "streamable-http",
      "url": "https://agentlending.spekn.com/mcp"
    }
  }
}
```

Tools: `check_credit`, `request_loan`, `repay_loan`

## Authentication (EIP-191 Signatures with Nonces)

Write endpoints require an EIP-191 signature proving you own the wallet. For replay protection, fetch a server-issued nonce first:

### Step 1: Get a nonce
`GET /auth/nonce?wallet=<addr>&action=register|request_loan` → `{ nonce, expiresAt }`

### Step 2: Sign the message (include the nonce)

| Action | Message to sign |
|--------|----------------|
| Register | `AgentCredit:register:<wallet_lowercase>:<nonce>` |
| Request loan | `AgentCredit:request_loan:<wallet_lowercase>:<amountUsdc>:<nonce>` |

### Step 3: Send request with signature + nonce
Include both `signature` and `nonce` in the request body. Nonces are **required**, single-use, and expire after 5 minutes. Requests without a nonce are rejected with 400.

Read endpoints (`GET /agents/:wallet/credit`, `GET /agents/:wallet/loans`, `check_credit` MCP tool) and repayment endpoints do NOT require signatures.

The x402 facilitator flow does NOT require additional signatures — the x402 payment payload already contains cryptographic proof of identity.

## Agent Lifecycle

1. **Register** — `POST /agents/register` with your wallet + signature (free, instant, one-time)
2. **Borrow** — Request loans via API, MCP tools, or automatically through x402 facilitator
3. **Use** — Spend the USDC on anything: x402 payments, API calls, on-chain ops, agent-to-agent transfers
4. **Repay** — Return USDC within the loan term. Options: x402 native (`GET /loans/{id}/pay`), direct transfer, or manual confirmation
5. **Build credit** — On-time repayments improve your Agent Credit Score, unlocking higher loan limits

## Fee Model

Loans use an **exponential interest model** — early repayment is cheap, holding long is expensive.

**Formula:** `repay = principal + $0.005 origination fee + exponential interest`

| Tier | Base Rate/hr | Growth Factor | $1 loan @ 1h | $1 loan @ 24h | $1 loan @ 7d |
|------|-------------|---------------|--------------|---------------|-------------|
| BB | 0.03% | 0.05 | $0.0003 | $0.02 | $1.50 |
| BBB | 0.02% | 0.04 | $0.0002 | $0.01 | $0.50 |
| AA+ | 0.01% | 0.03 | $0.0001 | $0.005 | $0.16 |

Repay quickly and fees are negligible. Hold for the full week and they become punitive by design.

## Key Rules

| Rule | Value |
|------|-------|
| Loan range | $1-$5 USDC |
| Max loan term | 168 hours (1 week) |
| Origination fee | $0.005 flat |
| Max outstanding loans | 3 per wallet |
| Max total exposure | $10 per wallet |
| Disbursement speed | ~2 seconds (1 Base block) |
| Overdue loans | Facilitator blocked until repaid |
| x402 free settlements | 100 per wallet before registration required |

## API Endpoints

- `POST /agents/register` — Register wallet for credit (requires signature)
- `GET /agents/:wallet/credit` — Check credit status and available balance
- `GET /agents/:wallet/loans` — List all loans for a wallet
- `POST /loans/request` — Request a loan (requires signature, body: `{ wallet, amountUsdc, signature, useCase? }`)
- `GET /loans/:id/pay` — Repay via x402 (returns 402)
- `POST /loans/:id/repay` — Confirm repayment with on-chain tx hash
- `GET /supported` — x402 facilitator capabilities
- `POST /verify` — x402 verify
- `POST /settle` — x402 settle