Skip to content

internet-court/internet-court-skill / vendored/near/near-intents

near-intents

Verified

Cross-chain token swap integration using NEAR Intents 1Click API. Use when building swap widgets, bridge interfaces, or multi-chain transfers across EVM, Solana, NEAR, TON, Stellar, and Tron.

FileKindSize
LICENSEother329 B
SKILL.mdskill md3.7 KB
references/concepts.mdmarkdown2.1 KB
rules/api-any-input-withdrawals.mdmarkdown2.1 KB
rules/api-deposit-submit.mdmarkdown1.4 KB
rules/api-quote.mdmarkdown8.3 KB
rules/api-status.mdmarkdown2.0 KB
rules/api-tokens.mdmarkdown1.2 KB
rules/deposit-evm.mdmarkdown847 B
rules/deposit-near.mdmarkdown1.6 KB
rules/deposit-solana.mdmarkdown1.7 KB
rules/deposit-stellar.mdmarkdown1.6 KB
rules/deposit-ton.mdmarkdown1.5 KB
rules/deposit-tron.mdmarkdown1.0 KB
rules/intents-balance.mdmarkdown1.9 KB
rules/passive-deposit.mdmarkdown1.5 KB
rules/react-hooks.mdmarkdown3.8 KB
rules/react-swap-widget.mdmarkdown14.2 KB
rules/server-example.mdmarkdown9.1 KB

rules/api-quote.md

View on GitHub
---
title: POST /v0/quote
impact: CRITICAL
tags: api, quote, swap
---

# POST /v0/quote

Generates swap quote. Use `dry: true` for preview, `dry: false` to get deposit address.

## Request Fields

### Required

| Field | Type | Description |
|-------|------|-------------|
| `dry` | boolean | `true` = preview only (no deposit address generated). `false` = commit quote, returns deposit address valid ~10 minutes |
| `swapType` | string | How to interpret `amount`. See Swap Types below |
| `originAsset` | string | Source token `assetId` from GET /v0/tokens |
| `destinationAsset` | string | Destination token `assetId` from GET /v0/tokens |
| `amount` | string | Amount in smallest unit (wei, lamports, satoshis). Interpreted based on `swapType` |
| `recipient` | string | Address to receive output tokens. Format depends on destination chain |
| `refundTo` | string | Address for refunds if swap fails. Must be valid for origin chain |

### Optional - Routing

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `depositType` | string | `ORIGIN_CHAIN` | Where you'll deposit from. `ORIGIN_CHAIN` = deposit on source blockchain. `INTENTS` = deposit from intents.near balance |
| `recipientType` | string | `DESTINATION_CHAIN` | Where output goes. `DESTINATION_CHAIN` = send to destination blockchain. `INTENTS` = credit to intents.near balance |
| `refundType` | string | `ORIGIN_CHAIN` | Where refunds go. `ORIGIN_CHAIN` = refund to source blockchain. `INTENTS` = refund to intents.near balance |
| `depositMode` | string | `SIMPLE` | `SIMPLE` = standard deposit address. `MEMO` = deposit address + memo (required for Stellar) |

### Optional - Pricing

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `slippageTolerance` | number | - | Max acceptable slippage in basis points. 100 = 1%. Affects `minAmountOut` |
| `deadline` | string | ~10min | ISO timestamp. Quote expires after this. User must deposit before deadline |
| `quoteWaitingTimeMs` | number | 3000 | How long to wait for market maker quotes (ms). Use `0` for fastest response |

### Optional - Fees & Tracking

| Field | Type | Description |
|-------|------|-------------|
| `referral` | string | Your app identifier (lowercase). Shown in on-chain data and analytics |
| `appFees` | array | Your fee: `[{ recipient: "yourfee.near", fee: 100 }]`. Fee in basis points (100 = 1%) |
| `sessionId` | string | Client session ID for tracking |
| `connectedWallets` | string[] | User's connected wallet addresses (helps with routing) |

### Optional - Virtual Chain (Advanced)

| Field | Type | Description |
|-------|------|-------------|
| `virtualChainRecipient` | string | EVM address for virtual chain recipient |
| `virtualChainRefundRecipient` | string | EVM address for virtual chain refunds |
| `customRecipientMsg` | string | Message for `ft_transfer_call` on NEAR. WARNING: Funds lost if recipient doesn't implement `ft_on_transfer` |

---

## Swap Types

### EXACT_INPUT (most common)

Fixed input amount, variable output.

```typescript
{ swapType: 'EXACT_INPUT', amount: '1000000' } // I want to swap exactly 1 USDC
```

**Behavior:**
- Deposit exactly `amountIn` → receive `amountOut`
- Deposit < `amountIn` → refunded by deadline
- Deposit > `amountIn` → swap processed, excess refunded after completion

### EXACT_OUTPUT

Fixed output amount, variable input.

```typescript
{ swapType: 'EXACT_OUTPUT', amount: '1000000000000000000' } // I want exactly 1 ETH out
```

**Response includes:** `minAmountIn`, `maxAmountIn`

**Behavior:**
- Deposit between `minAmountIn` and `maxAmountIn` → receive exact `amountOut`
- Deposit < `minAmountIn` → refunded
- Deposit > `maxAmountIn` → swap processed, excess refunded

### FLEX_INPUT

Variable input with slippage range. Good for "swap all" scenarios.

```typescript
{ swapType: 'FLEX_INPUT', amount: '1000000', slippageTolerance: 100 }
```

**Response includes:** `minAmountIn`, `minAmountOut`

**Behavior:**
- Any deposit ≥ `minAmountIn` accepted
- Output guaranteed ≥ `minAmountOut`
- Slippage applies to both input and output ranges

### ANY_INPUT

Accumulating deposits. Multiple deposits accepted until deadline.

```typescript
{ swapType: 'ANY_INPUT', amount: '0' } // No fixed amount
```

**Use case:** Aggregate multiple deposits, then withdraw via `/v0/any-input/withdrawals`

---

## Response Fields

```typescript
{
  correlationId: string;      // Unique quote ID
  timestamp: string;          // When quote was generated
  quoteRequest: { ... };      // Echo of your request
  quote: {
    // Deposit info (only when dry: false)
    depositAddress: string;   // Send tokens HERE
    depositMemo: string | null; // Include in tx if non-null (Stellar)

    // Amounts
    amountIn: string;         // Expected input (smallest unit)
    amountInFormatted: string; // Human readable "1.00"
    amountInUsd: string;      // USD value (display only)

    minAmountIn?: string;     // For EXACT_OUTPUT, FLEX_INPUT
    maxAmountIn?: string;     // For EXACT_OUTPUT

    amountOut: string;        // Expected output (smallest unit)
    amountOutFormatted: string; // Human readable
    amountOutUsd: string;     // USD value (DISPLAY ONLY - never use in logic)

    minAmountOut?: string;    // Guaranteed minimum after slippage

    // Timing
    deadline: string;         // ISO timestamp - deposit must arrive before this
    timeWhenInactive: string; // When quote becomes stale (only when dry: false)
    timeEstimate: number;     // Expected completion time in seconds
  }
}
```

---

## Examples

### Basic Swap (ETH USDC → NEAR)

```typescript
// Preview
const preview = await fetch('https://1click.chaindefuser.com/v0/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    dry: true,
    swapType: 'EXACT_INPUT',
    originAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near',
    destinationAsset: 'nep141:wrap.near',
    amount: '1000000', // 1 USDC (6 decimals)
    recipient: 'user.near',
    refundTo: '0xYourEthAddress',
    slippageTolerance: 100, // 1%
  })
}).then(r => r.json());

// preview.quote.amountOutFormatted = "0.35" (wNEAR)
```

### Commit & Get Deposit Address

```typescript
const committed = await fetch('https://1click.chaindefuser.com/v0/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY' // Avoid 0.1% fee
  },
  body: JSON.stringify({
    dry: false, // Commit!
    swapType: 'EXACT_INPUT',
    originAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near',
    destinationAsset: 'nep141:wrap.near',
    amount: '1000000',
    recipient: 'user.near',
    refundTo: '0xYourEthAddress',
    slippageTolerance: 100,
    referral: 'myapp',
    appFees: [{ recipient: 'myfees.near', fee: 50 }], // 0.5% fee
  })
}).then(r => r.json());

// committed.quote.depositAddress = "0x..." → send 1 USDC here
// committed.quote.deadline = "2025-01-16T15:00:00Z" → must deposit before
```

### Stellar (MEMO Required)

```typescript
const stellarQuote = await fetch('https://1click.chaindefuser.com/v0/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    dry: false,
    depositMode: 'MEMO', // REQUIRED for Stellar
    swapType: 'EXACT_INPUT',
    originAsset: 'nep141:stellar-native.omft.near',
    destinationAsset: 'nep141:wrap.near',
    amount: '10000000', // 1 XLM (7 decimals)
    recipient: 'user.near',
    refundTo: 'GAXYZ...', // Stellar address
  })
}).then(r => r.json());

// stellarQuote.quote.depositAddress = "GABCD..."
// stellarQuote.quote.depositMemo = "123456" → MUST include in Stellar tx or funds lost
```

### Intents Balance (Deposit to Balance)

```typescript
const toIntents = await fetch('https://1click.chaindefuser.com/v0/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    dry: false,
    swapType: 'EXACT_INPUT',
    originAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near',
    destinationAsset: 'nep141:eth-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.omft.near', // Same!
    depositType: 'ORIGIN_CHAIN',
    recipientType: 'INTENTS', // Credit to intents balance
    recipient: 'user.near', // NEAR account to credit
    refundTo: '0xYourEthAddress',
    amount: '1000000',
  })
}).then(r => r.json());
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall