surgecode/near-intents-skill
Overview
This skill integrates cross-chain token swaps using the NEAR Intents 1Click REST API. It provides a clear flow to fetch supported tokens, request quotes (preview and deposit), build deposit transactions for multiple chains, submit deposits, and poll swap status until completion. Use it to add swap widgets, bridge interfaces, or multi-chain transfer flows that rely on on-demand deposit addresses and automated post-deposit handling.
How this skill works
The integration fetches /v0/tokens for canonical assetId values, requests a quote via POST /v0/quote (dry=true for preview, dry=false to receive a short-lived deposit address), then you construct and send the chain-specific deposit transaction. After sending the deposit you POST /v0/deposit/submit to notify the API and poll GET /v0/status until the swap reaches a terminal state (SUCCESS, FAILED, REFUNDED, INCOMPLETE_DEPOSIT). Deposit addresses are typically valid for about 10 minutes.
When to use it
- Building an in-app swap widget for multi-chain token transfers
- Implementing a bridge interface that needs on-demand deposit addresses
- Server-side automation to orchestrate swaps across EVM, Solana, NEAR, TON, TRON, and Stellar
- Creating a QR/manual transfer flow with passive deposit monitoring
- When you need canonical asset identifiers and a single API to manage cross-chain lifecycle
Best practices
- Always use assetId from GET /v0/tokens; never construct asset identifiers manually
- Request a dry quote (dry=true) for UI previews and pricing, then request wet quote (dry=false) to get a deposit
- Cache tokens list and refresh periodically to avoid unnecessary calls
- Poll /v0/status until a terminal state and handle all terminal codes explicitly
- Follow chain-specific deposit docs for correct transaction construction (EVM, Solana, NEAR, TON, TRON, Stellar)
Example use cases
- React swap widget that previews price, requests deposit address, and submits deposit using wallet connectors
- Node.js server flow to create wet quotes, generate deposit transactions server-side, and monitor completion
- Bridge interface where users send native tokens to a provided deposit address and receive assets on another chain
- Passive QR code deposit flow where a user scans and sends funds, and the backend polls status to credit the recipient
- Advanced integration holding balances in intents.near for faster recurring swaps
FAQ
Deposit addresses from a wet quote are short-lived—generally valid for about 10 minutes. Request a new wet quote if it expires.
When should I use dry vs wet quotes?
Use dry=true for previews and UI pricing. Use dry=false to obtain a deposit address and proceed with the actual transfer.
What status values should I handle?
Poll until a terminal status: SUCCESS, FAILED, REFUNDED, or INCOMPLETE_DEPOSIT, and implement logic for each case.
