near-intents

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 and the @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

---

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

Parameter	Type	Required	Description
assetIn	string	✅	Origin asset symbol (e.g., 'NEAR', 'base:USDC', 'arb:ARB')
assetOut	string	✅	Destination asset symbol
amount	string	✅	Human-readable amount (e.g., '1.0', '0.5')
recipient	string	❌	Destination address. Required for cross-chain. Defaults to NEAR account
refundAddress	string	⚠️	REQUIRED for non-NEAR origins. Address on origin chain for refunds if swap fails. CRITICAL for fund safety!
mode	string	❌	'auto' sends deposit automatically from NEAR account. 'manual' returns quote + deposit address for user to send manually
swapType	string	❌	'EXACT_INPUT' (amount = input), 'EXACT_OUTPUT' (amount = desired output)

⚠️ 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 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 and NEAR Intents

License

MIT