⚡

// Skill profile

NEAR Intents Skill — 1Click SDK

Name: NEAR Intents Skill — 1Click SDK
Author: cuongdcdev

name: near-intents

by cuongdcdev · published 2026-03-22

开发工具API集成加密货币

Total installs

Stars

★ 0

Last updated

2026-03

// Install command

$ claw add gh:cuongdcdev/cuongdcdev-near-intents

View on GitHub

// Full documentation

---

name: near-intents

description: Universal cross-chain swap & bridge skill for OpenClaw using the NEAR Intents 1Click SDK. Supports 14+ blockchains including NEAR, Base, Ethereum, Solana, and Bitcoin.

---

# 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`:

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

|-------------|--------|----------|-------------|

⚠️ CRITICAL: Refund Address Safety

**When `assetIn` is on a non-NEAR chain** (e.g., `'base:USDC'`, `'arb:ARB'`, `'btc:BTC'`):

1. **`refundAddress` is REQUIRED** — the function will throw an error if missing

2. **ALWAYS ask the user** for their wallet address on the origin chain

3. **NEVER assume or guess** — using the wrong address = permanent fund loss

4. **Explain to the user**: "If the swap fails, your tokens will be refunded to this address"

**Example**:

// ❌ WRONG - Missing refundAddress for non-NEAR origin
await executeIntent({
  assetIn: 'base:USDC',  // Base origin
  assetOut: 'NEAR',
  amount: '0.5',
  recipient: 'user.near',
  mode: 'manual'
});
// → Error: Cross-chain swap from base:USDC requires refundAddress parameter

// ✅ CORRECT - User's Base wallet address provided
await executeIntent({
  assetIn: 'base:USDC',
  assetOut: 'NEAR',
  amount: '0.5',
  recipient: 'user.near',
  refundAddress: '0x123...',  // User's Base address
  mode: 'manual'
});

**Why this matters**:

Swaps can fail due to market conditions, liquidity issues, or timing

Failed swaps trigger automatic refunds to `refundAddress` on the **origin chain**

If `refundAddress` is wrong or belongs to someone else, **funds are permanently lost**

Returns

**Auto mode**: `"Swap Successful! 1.0 NEAR → 0.97 USDC\nTransaction: https://nearblocks.io/txns/...\nExplorer: https://explorer.near-intents.org/transactions/..."`

**Manual mode**: Formatted instructions with deposit address, amounts, tracking URL, and deadline

---

Asset Naming

Use `chain:SYMBOL` format. Omit chain prefix for NEAR-native tokens.

| Chain | Prefix | Examples |

|-----------|------------|-----------------------------------|

| NEAR | *(none)* | `NEAR`, `USDC`, `USDT`, `wNEAR` |

| Base | `base:` | `base:USDC` |

| Ethereum | `eth:` | `eth:ETH`, `eth:USDC` |

| Arbitrum | `arb:` | `arb:USDC`, `arb:ARB` |

| Solana | `sol:` | `sol:SOL`, `sol:USDC` |

| BSC | `bsc:` | `bsc:USDC` |

| Bitcoin | `btc:` | `btc:BTC` *(native only)* |

| Dogecoin | `doge:` | `doge:DOGE` *(native only)* |

| Zcash | `zec:` | `zec:ZEC` *(native only)* |

| Litecoin | `ltc:` | `ltc:LTC` *(native only)* |

**Case-insensitive**: `near`, `NEAR`, `Near` all work

**UTXO chains** (BTC, DOGE, ZEC, LTC): **native tokens only** — no wrapped/ERC-20 equivalents

---

Modes

Auto Mode (default)

Automatically sends the deposit from the configured NEAR account.

**Use when**: Origin asset is on NEAR and agent has NEAR credentials in `.env`.

await executeIntent({
  assetIn: 'NEAR',
  assetOut: 'base:USDC',
  amount: '1.0',
  recipient: '0xYourBaseAddress',
});

Manual Mode

Returns a quote with deposit address — the user (or agent) sends tokens separately.

**Use when**: Origin is on a non-NEAR chain, or you want to show the user a quote first.

const quote = await executeIntent({
  assetIn: 'arb:USDC',
  assetOut: 'sol:USDC',
  amount: '5.0',
  recipient: 'YourSolanaAddress',
  mode: 'manual',
});
// Returns deposit address + instructions

EXACT_OUTPUT

Specify the desired output amount; the 1Click API tells you how much to send.

const quote = await executeIntent({
  assetIn: 'USDT',
  assetOut: 'base:USDC',
  amount: '10.0',          // Want exactly 10 USDC out
  recipient: '0x...',
  mode: 'manual',
  swapType: 'EXACT_OUTPUT',
});

---

Examples

1. Swap NEAR → USDC on Base (Auto)

await executeIntent({
  assetIn: 'NEAR',
  assetOut: 'base:USDC',
  amount: '1.0',
  recipient: '0xYourBaseAddress',
});

2. Bridge USDC from Arbitrum → Solana (Manual)

const quote = await executeIntent({
  assetIn: 'arb:USDC',
  assetOut: 'sol:USDC',
  amount: '5.0',
  recipient: 'YourSolanaAddress',
  refundAddress: '0xYourArbitrumAddress',  // REQUIRED for refunds
  mode: 'manual',
});
// User sends 5 USDC to the deposit address on Arbitrum

3. Swap NEAR → USDC (same chain)

await executeIntent({
  assetIn: 'NEAR',
  assetOut: 'USDC',
  amount: '2.0',
});

4. Get a quote: How much NEAR for 10 USDC on Arbitrum?

const quote = await executeIntent({
  assetIn: 'NEAR',
  assetOut: 'arb:USDC',
  amount: '10.0',
  recipient: '0xYourArbAddress',
  mode: 'manual',
  swapType: 'EXACT_OUTPUT',
});

5. Send BTC to NEAR address

const quote = await executeIntent({
  assetIn: 'btc:BTC',
  assetOut: 'NEAR',
  amount: '0.01',
  recipient: 'yourname.near',
  refundAddress: 'bc1q...',  // REQUIRED - Your Bitcoin address
  mode: 'manual',
});
// User sends 0.01 BTC to the deposit address on Bitcoin

---

Configuration

`.env` file (only needed for auto mode with NEAR origin):

NEAR_ACCOUNT_ID=your-account.near
NEAR_PRIVATE_KEY=ed25519:your_private_key_here
NEAR_RPC_URL=https://rpc.mainnet.fastnear.com
NEAR_NETWORK_ID=mainnet
ONE_CLICK_JWT=optional_jwt_token

`ONE_CLICK_JWT`: Register at [partners.near-intents.org](https://partners.near-intents.org/) to avoid the 0.2% fee.

Skip `.env` entirely if only using manual mode for non-NEAR-origin swaps.

⚠️ **Never commit `.env` to version control!**

---

Under the Hood — 1Click SDK Flow

executeIntent()
  │
  ├─ 1. resolveToken(assetIn)  →  { symbol, decimals, assetId }
  ├─ 2. resolveToken(assetOut) →  { symbol, decimals, assetId }
  ├─ 3. toSmallestUnit(amount, decimals)
  │
  ├─ 4. OneClickService.getQuote({
  │       originAsset, destinationAsset, amount,
  │       refundTo, recipient, deadline, ...
  │    })
  │    → Returns { depositAddress, amountIn, amountOut }
  │
  ├─ [manual mode] → return quote instructions
  │
  ├─ 5. account.transfer() → send deposit to depositAddress
  ├─ 6. OneClickService.submitDepositTx() → (optional, speeds up)
  └─ 7. OneClickService.getExecutionStatus() → poll until SUCCESS

Swap Statuses

| Status | Meaning |

|---------------------|---------|

| `PENDING_DEPOSIT` | Waiting for deposit |

| `PROCESSING` | Deposit detected, market makers executing |

| `SUCCESS` | Tokens delivered to recipient |

| `INCOMPLETE_DEPOSIT`| Deposit below required amount |

| `REFUNDED` | Swap failed, tokens returned to refund address |

| `FAILED` | Swap failed due to error |

---

Token Map (built-in)

The code includes a static `TOKEN_MAP` for common tokens:

| Key | Asset ID (NEP-141) | Decimals |

|--------------|-----------------------------------------------------------------|----------|

| `NEAR` | `nep141:wrap.near` | 24 |

| `USDC` | `nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1` | 6 |

| `USDT` | `nep141:usdt.tether-token.near` | 6 |

| `base:USDC` | `nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near` | 6 |

| `arb:USDC` | `nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near` | 6 |

| `arb:ARB` | `nep141:arb-0x912ce59144191c1204e64559fe8253a0e49e6548.omft.near` | 18 |

| `eth:ETH` | `nep141:eth.omft.near` | 18 |

| `eth:USDC` | `nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near` | 6 |

| `sol:SOL` | `nep141:sol.omft.near` | 9 |

| `sol:USDC` | `nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near` | 6 |

To add more tokens: use `OneClickService.getTokens()` or check `TOKENS.md`.

---

Decimals Quick Reference

| Token | Decimals | `"1.0"` → smallest unit |

|-------|----------|------------------------|

| NEAR | 24 | `1000000000000000000000000` |

| USDC | 6 | `1000000` |

| USDT | 6 | `1000000` |

| ETH | 18 | `1000000000000000000` |

| SOL | 9 | `1000000000` |

| BTC | 8 | `100000000` |

Decimal conversion is handled automatically by `index.ts` using `decimal.js`.

---

Tracking & Explorer

**NEAR transactions**: `https://nearblocks.io/txns/<txHash>`

**1Click swap status**: `https://explorer.near-intents.org/transactions/<depositAddress>`

---

Troubleshooting

| Error | Solution |

|-------|----------|

| `Token not found: X` | Check symbol and chain prefix. See `TOKEN_MAP` or `TOKENS.md` |

| `No deposit address in quote response` | Solver couldn't match the pair/amount. Try a different amount or pair |

| `NEAR_ACCOUNT_ID and NEAR_PRIVATE_KEY must be set` | Configure `.env` or use `mode: 'manual'` |

| `Swap failed with status: REFUNDED` | Tokens returned to refund address. Retry with different amount |

| `Status polling timed out` | Check explorer URL manually. Swap may still complete |

| 401 Authentication error | JWT is invalid or expired. Register at partners.near-intents.org |

---

Dependencies

{
  "@defuse-protocol/one-click-sdk-typescript": "0.1.1",
  "@near-js/accounts": "^2.2.4",
  "@near-js/crypto": "^2.2.4",
  "@near-js/providers": "^2.2.4",
  "@near-js/signers": "^2.2.4",
  "@near-js/tokens": "^2.2.4",
  "decimal.js": "^10.4.3",
  "dotenv": "^16.3.1"
}

---

Files Overview

| File | Purpose |

|------|---------|

| `index.ts` | Main entry — exports `executeIntent()` |

| `lib-1click/` | Step-by-step 1Click SDK examples (get tokens, get quote, send deposit, etc.) |

| `SKILL.md` | This file — **primary AI agent reference** |

| `AI-AGENT-GUIDE.md` | Detailed agent workflow guide |

| `TOKENS.md` | Full token reference with decimals and asset IDs |

| `manifest.json` | Skill manifest for OpenClaw |

| `README.md` | Project documentation |

| `USAGE_GUIDE.md` | Usage patterns and troubleshooting |

---

Version

**v2.0.0** — Powered by [1Click SDK](https://github.com/defuse-protocol/one-click-sdk-typescript) and [NEAR Intents](https://docs.near-intents.org)

License

MIT

// Comments

// Related skills

More tools from the same signal band

Order food/drinks (点餐) on an Android device paired as an OpenClaw node. Uses in-app menu and cart; add goods, view cart, submit order (demo, no real payment).

Sign plugins, rotate agent credentials without losing identity, and publicly attest to plugin behavior with verifiable claims and authenticated transfers.

The philosophical layer for AI agents. Maps behavior to Spinoza's 48 affects, calculates persistence scores, and generates geometric self-reports. Give your...

日历管理数据处理

1 installs★ 0