feat: near intents swapper (#11016)

Author: gomesalexandre

.claude/skills/swapper-integration/NEAR_INTENTS_RESEARCH.md

@@ -221,7 +221,133 @@ Create `packages/swapper/src/swappers/[SwapperName]Swapper/`
 
 **Refer to** `@examples.md` for code templates. **Copy patterns** from similar existing swappers.
 
-#### Step 3: Register the swapper
+#### Step 3: Add Swapper-Specific Metadata (ONLY if needed)
+
+**When is metadata needed?**
+- Deposit-to-address swappers (Chainflip, NEAR Intents) - need deposit address, swap ID for status polling
+- Order-based swappers (CowSwap) - need order ID for status tracking
+- Any swapper that requires tracking state between quote → execution → status polling
+
+**When is metadata NOT needed?**
+- Direct transaction swappers (Bebop, 0x, Portals) - transaction is built from quote, no async tracking needed
+- Same-chain aggregators where transaction hash is sufficient for status tracking
+- Most EVM-only swappers that return transaction data directly
+
+**If your swapper doesn't need async status polling or deposit addresses, skip this step!**
+
+**Three places to add metadata:**
+
+**a. Define types** (`packages/swapper/src/types.ts`):
+
+Add to `TradeQuoteStep` type:
+```typescript
+export type TradeQuoteStep = {
+  // ... existing fields
+  [swapperName]Specific?: {
+    depositAddress: string
+    swapId: number
+    // ... other swapper-specific fields
+  }
+}
+```
+
+Add to `SwapperSpecificMetadata` type (for swap storage):
+```typescript
+export type SwapperSpecificMetadata = {
+  chainflipSwapId: number | undefined
+  nearIntentsSpecific?: {
+    depositAddress: string
+    depositMemo?: string
+    timeEstimate: number
+    deadline: string
+  }
+  // Add your swapper's metadata here
+  [swapperName]Specific?: {
+    // ... fields needed for status polling
+  }
+  // ... other fields
+}
+```
+
+**b. Populate in quote** (`packages/swapper/src/swappers/[Swapper]/swapperApi/getTradeQuote.ts`):
+
+Store metadata in the TradeQuoteStep:
+```typescript
+const tradeQuote: TradeQuote = {
+  // ... other fields
+  steps: [{
+    // ... step fields
+    [swapperName]Specific: {
+      depositAddress: response.depositAddress,
+      swapId: response.id,
+      // ... other data needed later
+    }
+  }]
+}
+```
+
+**c. Extract into swap** (TWO places required!):
+
+**Place 1**: `src/components/MultiHopTrade/components/TradeConfirm/hooks/useTradeButtonProps.tsx`
+
+Add to metadata object around line 114-126:
+```typescript
+metadata: {
+  chainflipSwapId: firstStep?.chainflipSpecific?.chainflipSwapId,
+  nearIntentsSpecific: firstStep?.nearIntentsSpecific,
+  // Add your swapper's metadata extraction here:
+  [swapperName]Specific: firstStep?.[swapperName]Specific,
+  relayTransactionMetadata: firstStep?.relayTransactionMetadata,
+  stepIndex: currentHopIndex,
+  quoteId: activeQuote.id,
+  streamingSwapMetadata: { ... }
+}
+```
+
+**Place 2**: `src/lib/tradeExecution.ts` (CRITICAL - often forgotten!)
+
+Add to metadata object around line 156-161:
+```typescript
+metadata: {
+  ...swap.metadata,
+  chainflipSwapId: tradeQuote.steps[0]?.chainflipSpecific?.chainflipSwapId,
+  nearIntentsSpecific: tradeQuote.steps[0]?.nearIntentsSpecific,
+  // Add your swapper's metadata extraction here:
+  [swapperName]Specific: tradeQuote.steps[0]?.[swapperName]Specific,
+  relayTransactionMetadata: tradeQuote.steps[0]?.relayTransactionMetadata,
+  stepIndex,
+}
+```
+
+**Why both places?**
+- `useTradeButtonProps` creates the initial swap (before wallet signature)
+- `tradeExecution` updates the swap during execution (after wallet signature, with actual tradeQuote)
+- If you only add to one place, metadata will be missing!
+
+**d. Access in status check** (`packages/swapper/src/swappers/[Swapper]/endpoints.ts`):
+
+```typescript
+checkTradeStatus: async ({ config, swap }) => {
+  const { [swapperName]Specific } = swap?.metadata ?? {}
+
+  if (![swapperName]Specific?.swapId) {
+    throw new Error('swapId is required for status check')
+  }
+
+  // Use metadata to poll API
+  const status = await api.getStatus([swapperName]Specific.swapId)
+  // ...
+}
+```
+
+**Example: NEAR Intents metadata flow**
+```
+1. Quote: Store in step.nearIntentsSpecific.depositAddress
+2. Swap creation: Extract to swap.metadata.nearIntentsSpecific
+3. Status check: Read from swap.metadata.nearIntentsSpecific.depositAddress
+```
+
+#### Step 4: Register the swapper
 
 Update these files to register your new swapper:
 
@@ -234,12 +360,26 @@ Update these files to register your new swapper:
    - Export new swapper
 
 3. **`packages/swapper/src/types.ts`**
-   - Add transaction metadata type if needed
-   - Add API config fields
+   - Add API config fields (if not already done in metadata step)
 
 4. **CSP Headers** (if swapper calls external API):
-   - Add API domain to `headers/csps/index.ts`
-   - Create `headers/csps/defi/swappers/[SwapperName].ts` with CSP rules
+   - Create `headers/csps/defi/swappers/[SwapperName].ts`:
+     ```typescript
+     import type { Csp } from '../../../types'
+
+     export const csp: Csp = {
+       'connect-src': ['https://api.[swapper].com'],
+     }
+     ```
+   - Register in `headers/csps/index.ts`:
+     ```typescript
+     import { csp as [swapperName] } from './defi/swappers/[SwapperName]'
+
+     export const csps = [
+       // ... other csps
+       [swapperName],
+     ]
+     ```
 
 5. **UI Integration** (`src/`):
 
@@ -277,11 +417,14 @@ Update these files to register your new swapper:
 
    **d. Wire up feature flag:**
    - File: `src/state/helpers.ts`
-   - Add to `isCrossAccountTradeSupported` (if applicable)
-   - Add to `getEnabledSwappers`:
+   - Add to `isCrossAccountTradeSupported` function parameter and switch statement (if swapper supports cross-account)
+   - Add to `getEnabledSwappers` function:
      ```typescript
      export const getEnabledSwappers = (
-       { [SwapperName]Swap, ...otherFlags }: FeatureFlags,
+       {
+         [SwapperName]Swap,  // Add to destructured parameters
+         ...otherFlags
+       }: FeatureFlags,
        ...
      ): Record<SwapperName, boolean> => {
        return {
@@ -292,9 +435,15 @@ Update these files to register your new swapper:
      }
      ```
 
-   **e. Update test mocks (if applicable):**
+   **e. Update test mocks (REQUIRED):**
    - File: `src/test/mocks/store.ts`
-   - Add feature flag to mock state
+   - Add feature flag to mock featureFlags object:
+     ```typescript
+     featureFlags: {
+       // ... other flags
+       [SwapperName]Swap: false,
+     }
+     ```
 
 6. **Configuration**:
 

.claude/skills/swapper-integration/SKILL.md

@@ -35,6 +35,7 @@ VITE_FEATURE_ARBITRUM_BRIDGE=true
 VITE_FEATURE_CUSTOM_TOKEN_IMPORT=true
 VITE_FEATURE_USDT_APPROVAL_RESET=true
 VITE_FEATURE_PORTALS_SWAPPER=true
+VITE_FEATURE_NEAR_INTENTS_SWAP=false
 VITE_FEATURE_RUNEPOOL=true
 VITE_FEATURE_RUNEPOOL_DEPOSIT=true
 VITE_FEATURE_RUNEPOOL_WITHDRAW=true
@@ -188,6 +189,9 @@ VITE_FEATURE_BEBOP_SWAP=false
 VITE_CHAINFLIP_API_KEY=09bc0796ff40435482c0a54fa6ae2784
 VITE_CHAINFLIP_API_URL=https://chainflip-broker.io
 
+# NEAR Intents
+VITE_NEAR_INTENTS_API_KEY=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIwMjUtMDQtMjMtdjEifQ.eyJ2IjoxLCJrZXlfdHlwZSI6ImludGVncmF0aW9ucyIsInBhcnRuZXJfaWQiOiJnb21lcy1zaGFwZS1zaGlmdCIsImlhdCI6MTc2MjgxNjQ3MCwiZXhwIjoxNzk0MzUyNDcwfQ.BHFPJ1y-UnVBN3Y_PtMfP9MRng-hKPowYDLOeLj4Cnsvs9lNgikgaC_e41PO4LduMKiRRrtwfRhzUfV5Usdsf8IS9U7mF1UrUwDqyEEOF10weJWYU36Gg6NyNuIFgJhvV8sFzwPShbenLHIR3gIZ97pyBmpJ8jTDZu7ncw6kVqY6hcsu6H9Pyl9jYNdSwhdWUgZ9UswPPTeecrF1wgQPpE3i3tNT-fTbDtj-DswmEIT3f8qgfgZBi7cde68gsGiVy7v0cSE2r8y9UwFWejuUoltUDrTEmF6lCJHGuCaKYqGqZs2MBiIr5xnYpzlsKFTYlUNa8cTTcXng_pzWd5LrsA
+
 # relay
 VITE_FEATURE_SWAPPER_RELAY=true
 VITE_RELAY_API_URL=https://api.relay.link

.env

@@ -4,6 +4,7 @@
 
 # Swapper feature flags
 VITE_FEATURE_BEBOP_SWAP=true
+VITE_FEATURE_NEAR_INTENTS_SWAP=true
 
 # feature flags
 VITE_FEATURE_THORCHAIN_TCY_ACTIVITY=true

.env.development

@@ -0,0 +1,5 @@
+import type { Csp } from '../../../types'
+
+export const csp: Csp = {
+  'connect-src': ['https://1click.chaindefuser.com'],
+}

headers/csps/defi/swappers/NearIntents.ts

@@ -30,6 +30,7 @@ import { csp as zeroX } from './defi/swappers/0x'
 import { csp as bebop } from './defi/swappers/Bebop'
 import { csp as butterSwap } from './defi/swappers/ButterSwap'
 import { csp as cowSwap } from './defi/swappers/CowSwap'
+import { csp as nearIntents } from './defi/swappers/NearIntents'
 import { csp as oneInch } from './defi/swappers/OneInch'
 import { csp as portals } from './defi/swappers/Portals'
 import { csp as thor } from './defi/swappers/Thor'
@@ -107,6 +108,7 @@ export const csps = [
   zeroX,
   bebop,
   cowSwap,
+  nearIntents,
   oneInch,
   portals,
   thor,

headers/csps/index.ts

@@ -76,6 +76,7 @@
     "@chakra-ui/system": "^2.6.2",
     "@chakra-ui/tag": "^3.1.1",
     "@cowprotocol/app-data": "^2.3.0",
+    "@defuse-protocol/one-click-sdk-typescript": "^0.1.1-0.2",
     "@emotion/react": "^11.13.0",
     "@emotion/styled": "^11.13.0",
     "@formatjs/intl-getcanonicallocales": "^2.3.0",

package.json

@@ -14,6 +14,8 @@ import { jupiterApi } from './swappers/JupiterSwapper/endpoints'
 import { jupiterSwapper } from './swappers/JupiterSwapper/JupiterSwapper'
 import { mayachainApi } from './swappers/MayachainSwapper/endpoints'
 import { mayachainSwapper } from './swappers/MayachainSwapper/MayachainSwapper'
+import { nearIntentsApi } from './swappers/NearIntentsSwapper/endpoints'
+import { nearIntentsSwapper } from './swappers/NearIntentsSwapper/NearIntentsSwapper'
 import { portalsApi } from './swappers/PortalsSwapper/endpoints'
 import { portalsSwapper } from './swappers/PortalsSwapper/PortalsSwapper'
 import { relaySwapper } from './swappers/RelaySwapper'
@@ -80,12 +82,17 @@ export const swappers: Record<SwapperName, (SwapperApi & Swapper) | undefined> =
     ...bebopSwapper,
     ...bebopApi,
   },
+  [SwapperName.NearIntents]: {
+    ...nearIntentsSwapper,
+    ...nearIntentsApi,
+  },
   [SwapperName.Test]: undefined,
 }
 
 // Slippage defaults. Don't export these to ensure the getDefaultSlippageDecimalPercentageForSwapper helper function is used.
 const DEFAULT_SLIPPAGE_DECIMAL_PERCENTAGE = '0.002' // .2%
 const DEFAULT_COWSWAP_SLIPPAGE_DECIMAL_PERCENTAGE = '0.005' // .5%
+const DEFAULT_NEAR_INTENTS_SLIPPAGE_DECIMAL_PERCENTAGE = '0.005' // .5%
 const DEFAULT_PORTALS_SLIPPAGE_DECIMAL_PERCENTAGE = '0.025' // 2.5%
 const DEFAULT_THOR_SLIPPAGE_DECIMAL_PERCENTAGE = '0.01' // 1%
 const DEFAULT_MAYA_SLIPPAGE_DECIMAL_PERCENTAGE = '0.01' // 1%
@@ -120,6 +127,8 @@ export const getDefaultSlippageDecimalPercentageForSwapper = (
       throw new Error('Default slippage not supported by Relay')
     case SwapperName.ButterSwap:
       return DEFAULT_BUTTERSWAP_SLIPPAGE_DECIMAL_PERCENTAGE
+    case SwapperName.NearIntents:
+      return DEFAULT_NEAR_INTENTS_SLIPPAGE_DECIMAL_PERCENTAGE
     default:
       return assertUnreachable(swapperName)
   }

packages/swapper/src/constants.ts

@@ -0,0 +1,10 @@
+import type { Swapper } from '../../types'
+import { executeEvmTransaction, executeSolanaTransaction } from '../../utils'
+
+export const nearIntentsSwapper: Swapper = {
+  executeEvmTransaction,
+  executeSolanaTransaction,
+  executeUtxoTransaction: (txToSign, { signAndBroadcastTransaction }) => {
+    return signAndBroadcastTransaction(txToSign)
+  },
+}

packages/swapper/src/swappers/NearIntentsSwapper/NearIntentsSwapper.ts

@@ -0,0 +1,5 @@
+export const ONE_CLICK_BASE_URL = 'https://1click.chaindefuser.com'
+
+export const DEFAULT_SLIPPAGE_BPS = 50
+
+export const DEFAULT_QUOTE_DEADLINE_MS = 30 * 60 * 1000