Near Intents

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

⚠️ 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.

• 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: 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

Token Map (built-in)

The code includes a static TOKEN_MAP for common tokens:

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

Decimals Quick Reference

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

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

Version

v2.0.0 — Powered by 1Click SDK and NEAR Intents

License

MIT