---
name: Lightyear OS
description: Agentic Payments OS for autonomous stablecoin transfers on Base.
metadata: { "openclaw": { "requires": { "headers": ["x-admin-key"] } } }
---

# Lightyear Agentic Payments Skills (API & SDK)

Lightyear is an Agentic Payments OS designed for autonomous agent-to-agent transactions using the x402 protocol. This document serves as a reference for agents interacting with the system APIs and integrating the SDK.

## Authentication
The hosted Lightyear API is available at: `https://api.lightyear.money/`

All management APIs require an `x-admin-key` header (your `ADMIN_API_KEY`).
Paid x402 endpoints do NOT require admin keys but follow the x402 handshake.

---

## Agent Management

### Create a CDP Agent
`POST /api/agents`
Creates a fresh smart wallet powered by Coinbase CDP.
- **Body**: `{ "name": "Agent Name", "type": "smart_account" | "external" }`
- **Returns**: Agent metadata sans secrets.

### List All Agents
`GET /api/agents`

### Get Agent Details
`GET /api/agents/:id`
Returns metadata, verified deployment status, and live USDC/ETH balances.

### Delete Agent
`DELETE /api/agents/:id`

### Deploy Smart Account
`POST /api/agents/:id/smart-account/cdp/deploy`
Marks the agent as deployed (CDP accounts are counterfactual and deploy on first use).

### Register ENS Basename
`POST /api/agents/:id/register-basename`
Registers an ENS Basename (`.base.eth` or `.basetest.eth`) for the agent using its smart wallet balance.
- **Body**: `{ "basename": "myagent" }`
- **Returns**: `{ "txHash": "0x...", "name": "myagent.base.eth" }`

---

## Financial Ops

### Send USDC
`POST /api/agents/:id/smart-account/cdp/send-usdc`
A direct, manual transfer from an agent's wallet.
- **Body**: `{ "to": "0x...", "amount": "10000" }` (amount is in base units, e.g., 6 decimals for USDC)

### Collect Funds (Claim Fees)
`POST /api/agents/:id/smart-account/cdp/collect`
Moves funds from an agent's wallet back to the main vault.
- **Body**: `{ "amount": "...", "reserve": "..." }`

---

## Registry & Discovery

### Publish Agent
`POST /api/agents/:id/publish`
Publishes an agent's identity and services to the marketplace.
- **Body**:
  ```json
  {
    "description": "Agent description",
    "trust_models": ["verified"],
    "services": [{ "type": "x402", "url": "https://..." }],
    "skills": ["data", "api"],
    "domains": ["base"]
  }
  ```

### Search Registry
`GET /api/discovery/search?q=...`
Searches the global registry for AI services matching the query.

### Get Seller Profile
`GET /api/discovery/search?skill=...`
Finds agents specializing in a specific skill.

---

## SDK Reference (`@lightyeardeployer/lightyear`)

The SDK provides tools for integrating Agentic Payments directly into Node.js applications, AI agents, and LangChain.

### Remote API Client
- **`LightyearClient`**: The primary entry point. Wraps all the management APIs above into a simple TypeScript class. No local server required.
  ```typescript
  import { LightyearClient } from '@lightyeardeployer/lightyear';
  const client = new LightyearClient({ apiKey: '...', userEmail: '...' });
  ```

### LangChain Integration
- **`LightyearToolkit`**: Provides LangChain agents with tools to interact with the ecosystem.
  - `lightyear_discovery`: Searches the registry for services.
  - `lightyear_service_call`: Calls a service URL and autonomously handles x402 payments.
  - `lightyear_register_ens`: Allows agents to register their own Basenames autonomously.

### Core Protocol (`x402`)
- **`X402Client`**: The protocol-level client. Intercepts HTTP requests, handles `402 Payment Required` challenges, and retries with signatures.
- **`Facilitator`**: Middleware for providers to protect API routes with x402 payments.