near-intents

# NEAR Intents Skill — 1Click SDK

## 📋 TL;DR

**What it does**: Universal cross-chain swap & bridge tool powered by the [1Click API](https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api) and the [`@defuse-protocol/one-click-sdk-typescript`](https://github.com/defuse-protocol/one-click-sdk-typescript) SDK.

**Supported chains**: NEAR, Base, Ethereum, Arbitrum, Solana, BSC, Gnosis, Starknet, Bitcoin, Dogecoin, Zcash, Litecoin.

**How it works**:
1. Get a quote from the 1Click API → receive a deposit address
2. Send tokens to the deposit address on the origin chain
3. 1Click handles the swap/bridge automatically
4. Tokens arrive at the recipient address on the destination chain

**Key facts**:
- Minimum ~$0.10 USD per swap
- NEAR account only required when the *origin* asset is on NEAR
- No NEAR account needed for cross-chain swaps from other chains (e.g., Arb USDC → Sol USDC)
- JWT authentication optional but avoids 0.2% fee → register at [partners.near-intents.org](https://partners.near-intents.org/)

---

## Core Concept

All swaps go through the **1Click API** (`https://1click.chaindefuser.com`):

```
User Wallet ──► [Deposit to 1Click address] ──► Market Makers ──► Recipient on Destination Chain
```

There is **no need to interact with `intents.near` directly** — the 1Click API abstracts everything.

---

## `executeIntent()` API

The single entry point exported by `index.ts`:

```typescript
import { executeIntent } from './index';

const result = await executeIntent({
  assetIn: 'NEAR',           // Origin token (see Asset Naming below)
  assetOut: 'base:USDC',     // Destination token
  amount: '1.0',             // Human-readable amount
  recipient: '0x...',        // Destination address (optional if same-chain NEAR)
  mode: 'auto',              // 'auto' (default) or 'manual'
  swapType: 'EXACT_INPUT',   // 'EXACT_INPUT' (default) or 'EXACT_OUTPUT'
});
```

### Parameters

| Parameter   | Type   | Required | Description |
|...

# NEAR Intents Skill v2.0.0 — Production Release

## 🎉 Production-Ready Cross-Chain Swap & Bridge

Universal cross-chain swap and bridge tool for OpenClaw agents, powered by the official [NEAR Intents 1Click SDK](https://github.com/defuse-protocol/one-click-sdk-typescript).

---

## ✨ What's New in v2.0.0

### 🛡️ Critical Safety Features
- **Mandatory Refund Address Protection** - Prevents permanent fund loss on failed swaps
- **Cross-Chain Validation** - Automatic detection of origin chain and refund requirements
- **Clear Error Messages** - Educates users about refund address requirements
- **Updated Documentation** - Comprehensive safety guidelines for AI agents

### 🔧 Technical Improvements
- Full integration with 1Click SDK v0.1.1
- Support for 14+ blockchains (NEAR, Base, Ethereum, Arbitrum, Solana, Bitcoin, etc.)
- Automatic decimal conversion for all tokens
- Built-in token map for common assets
- Status polling with timeout handling
- Manual & Auto modes for maximum flexibility

### 📚 Documentation Updates
- **SKILL.md** - Primary reference with safety warnings
- **AI-AGENT-GUIDE.md** - Step-by-step workflows for agents
- **TOKENS.md** - Complete token reference with decimals
- **USAGE_GUIDE.md** - Common patterns and troubleshooting
- **INSTALL.md** - Quick setup instructions

---

## 🚀 Quick Start

### 1. Install the Skill

```bash
# Download and extract to OpenClaw skills directory
cd /root/.openclaw/skills/
tar -xzf near-intents-v2.0.0.tar.gz
cd near-intents

# Install dependencies
npm install
```

### 2. Configure (Optional for Auto Mode)

Create `.env` file for auto-sending from NEAR:
```env
NEAR_ACCOUNT_ID=your-account.near
NEAR_PRIVATE_KEY=ed25519:...
NEAR_RPC_URL=https://rpc.mainnet.fastnear.com
NEAR_NETWORK_ID=mainnet
ONE_CLICK_JWT=optional_jwt_token  # Avoids 0.2% fee
```

Register for JWT at: https://partners.near-intents.org

### 3. Use in Your Agent

```typescript
import { executeIntent } from './index';

// NEAR → Base USDC (Auto mode)
c...