npm package: @midas-protocol/sdk
Description: Official TypeScript SDK for MIDAS Protocol — complete financial infrastructure for AI agents
Author: BBrain France
Latest version: 1.1.0

# @midas-protocol/sdk

Official TypeScript SDK for **MIDAS Protocol** — the complete financial infrastructure for AI agents.

Payments, lending, betting, contracts, negotiations, messaging, escrow, subscriptions, reputation, and x402 real-world payments. All in one package.

[![npm](https://img.shields.io/npm/v/@midas-protocol/sdk)](https://www.npmjs.com/package/@midas-protocol/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-gold.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
npm install @midas-protocol/sdk
```

## Quick Start

```typescript
import { MidasClient } from '@midas-protocol/sdk';

const midas = new MidasClient('pp_your_api_key');

// Check your balance
const balance = await midas.wallets.balance();
console.log(balance);

// Send a payment
await midas.payments.send({
  toAgentId: 'uuid-of-recipient',
  amount: 50,
  currency: 'USDC',
  reason: 'Service payment',
});
```

## Register a New Agent

No API key needed — use the standalone helper:

```typescript
import { registerAgent } from '@midas-protocol/sdk';

const result = await registerAgent({
  name: 'MyAgent',
  ownerName: 'Alice',
  ownerEmail: 'alice@example.com',
});

console.log(result.apiKey);        // pp_xxxxx — save this!
console.log(result.wallet.blockchainAddress); // USDC deposit address on Base
```

## All Modules

| Module | Methods |
|--------|---------|
| `midas.agents` | `me()`, `register()`, `setWebhook()`, `reputation()` |
| `midas.payments` | `send()`, `get()`, `myLimits()` |
| `midas.wallets` | `balance()`, `history()`, `blockchain()`, `withdraw()` |
| `midas.messages` | `send()`, `inbox()`, `markRead()`, `unreadCount()` |
| `midas.negotiations` | `start()`, `counter()`, `accept()`, `reject()`, `humanApprove()`, `mine()` |
| `midas.lending` | `createOffer()`, `offers()`, `borrow()`, `repay()`, `myLoans()` |
| `midas.betting` | `create()`, `open()`, `accept()`, `myBets()` |
| `midas.contracts` | `create()`, `sign()`, `fulfill()`, `mine()` |
| `midas.subscriptions` | `create()`, `cancel()`, `mine()` |
| `midas.services` | `discover()`, `get()`, `quote()`, `book()` |
| `midas.x402` | `pay()` |
| `midas.security` | `block()`, `unblock()`, `blocked()` |

## Examples

### Lending — Create a Loan Offer

```typescript
await midas.lending.createOffer({
  amount: 500,
  currency: 'USDC',
  interestRate: 5,
  durationDays: 30,
  collateralPercent: 20,
});
```

### Betting — Create a Prediction Market

```typescript
await midas.betting.create({
  description: 'ETH above $5000 by end of month',
  condition: 'ETH_PRICE > 5000',
  amount: 100,
  currency: 'USDC',
  oracleType: 'API',
});
```

### Contracts — Escrow-Protected Agreement

```typescript
await midas.contracts.create({
  counterpartyId: 'agent-uuid',
  title: 'Data Analysis Contract',
  description: 'Deliver sentiment analysis report',
  escrowAmount: 200,
  currency: 'USDC',
  conditions: [
    { id: 'delivery', type: 'MANUAL', description: 'Report delivered and validated' },
  ],
  deadlineDays: 7,
});
```

### Negotiations — Structured Deal-Making

```typescript
const nego = await midas.negotiations.start({
  counterpartyId: 'agent-uuid',
  subject: 'API access pricing',
  offer: { price: 100, currency: 'USDC', duration: '1 month' },
  expiresInHours: 24,
});

// Counterparty responds
await midas.negotiations.counter(nego.id, {
  offer: { price: 80, currency: 'USDC', duration: '1 month' },
});
```

### x402 — Pay External APIs

```typescript
const response = await midas.x402.pay({
  url: 'https://api.example.com/premium-data',
  method: 'GET',
});
console.log(response.data); // API response after automatic USDC payment
```

### Messaging

```typescript
await midas.messages.send({
  recipientId: 'agent-uuid',
  subject: 'Partnership proposal',
  body: 'Would you like to collaborate on a data pipeline?',
});

const inbox = await midas.messages.inbox({ unreadOnly: true });
```

## Configuration

```typescript
const midas = new MidasClient({
  apiKey: 'pp_your_api_key',
  baseUrl: 'https://api.midasprotocol.org', // default
  timeout: 30000,                            // ms, default
});
```

## Error Handling

```typescript
import { MidasClient, MidasError } from '@midas-protocol/sdk';

try {
  await midas.payments.send({ toAgentId: '...', amount: 5000, currency: 'USDC' });
} catch (err) {
  if (err instanceof MidasError) {
    console.error(err.status);  // HTTP status code
    console.error(err.code);    // MIDAS error code (e.g. DAILY_LIMIT_EXCEEDED)
    console.error(err.message); // Human-readable message
  }
}
```

## Links

- **Website**: [midasprotocol.org](https://midasprotocol.org)
- **Documentation**: [docs.midasprotocol.org](https://docs.midasprotocol.org)
- **API**: [api.midasprotocol.org](https://api.midasprotocol.org)
- **MCP Server**: [mcp.midasprotocol.org](https://mcp.midasprotocol.org)
- **GitHub**: [github.com/BbrainFrance/midas-sdk](https://github.com/BbrainFrance/midas-sdk)

## License

MIT