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

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

**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`.

### 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.

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

---

## Examples

### 1. Swap NEAR → USDC on Base (Auto)

---

## Configuration

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

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

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

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'
});