|
| 1 | +--- |
| 2 | +name: across protocol skill for agents |
| 3 | +description: End-to-end Across Protocol integration playbook. Default to Swap API for all crosschain bridging and swapping. Covers intent lifecycle, Swap API integration, embedded crosschain actions, deposit tracking, fee collection, and security checklists. |
| 4 | +user-invocable: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Across Protocol Development Skill |
| 8 | + |
| 9 | +## What this Skill is for |
| 10 | +Use this Skill when the user asks for: |
| 11 | +- Crosschain bridge or swap integration (any-to-any token transfers) |
| 12 | +- Wallet or dApp integration with Across APIs |
| 13 | +- Embedded crosschain actions (bridge + mint/stake/deposit in one tx) |
| 14 | +- Deposit tracking and status monitoring |
| 15 | +- Fee quoting, transfer limits, or route discovery |
| 16 | +- Integrator fee collection setup |
| 17 | +- Onchain intent construction (ERC-7683 / SpokePool deposits) |
| 18 | +- Relayer operation or configuration |
| 19 | +- Security review of crosschain integration code |
| 20 | + |
| 21 | +## Default stack decisions (opinionated) |
| 22 | + |
| 23 | +### 1. Swap API first (recommended for most integrators) |
| 24 | +- Use `GET /swap/approval` for all crosschain swaps. It returns executable calldata — sign and submit. |
| 25 | +- Use `POST /swap/approval` when you need embedded destination actions (mint, stake, deposit). |
| 26 | +- The Swap API handles origin swaps, bridging, and destination swaps in a single call. |
| 27 | +- Supports `appFee` + `appFeeRecipient` natively for integrator fee collection. |
| 28 | + |
| 29 | + |
| 30 | +### 2. Trade type selection |
| 31 | +- **exactInput** (default): User specifies how much to send. Best for "swap X tokens" flows. |
| 32 | +- **minOutput**: User specifies minimum to receive. Best for simple swaps without post-bridge actions. |
| 33 | +- **exactOutput**: User needs a precise amount on destination. Best for multi-step flows (e.g., exact ERC-20 amount for a mint). Transaction reverts if exact amount can't be delivered. |
| 34 | + |
| 35 | +### 3. Slippage |
| 36 | +- Default to `slippage=auto` — the API picks an optimal value. |
| 37 | +- Only set a numeric slippage (0 to 1) when the user has a specific tolerance requirement. |
| 38 | +- Numeric slippage splits evenly across origin and destination legs. |
| 39 | + |
| 40 | +### 4. Refund behavior |
| 41 | +- **B2B / A2B routes** (no destination swap): refunds default to origin chain. |
| 42 | +- **B2A / A2A routes** (destination swap involved): refunds default to destination chain. |
| 43 | +- Override with `refundOnOrigin=true/false` when needed. |
| 44 | +- Refund recipient priority: `refundAddress` > `recipient` > `depositor`. |
| 45 | + |
| 46 | +## Operating procedure (how to execute tasks) |
| 47 | + |
| 48 | +### 1. Classify the task |
| 49 | +- **UI/wallet integration** — connecting a dApp to Across for crosschain transfers |
| 50 | +- **Backend/script** — server-side bridging, bot-driven transfers |
| 51 | +- **Embedded actions** — bridge + post-bridge contract call in one tx |
| 52 | +- **Tracking/monitoring** — deposit status, fill confirmation |
| 53 | +- **On-chain/ERC-7683** — direct SpokePool or AcrossOriginSettler interaction |
| 54 | +- **Relayer operation** — running or configuring a relayer node |
| 55 | + |
| 56 | +### 2. Pick the right integration path |
| 57 | + |
| 58 | +| Task | Use | |
| 59 | +|------|-----| |
| 60 | +| Crosschain swap (any token to any token) | Swap API `GET /swap/approval` | |
| 61 | +| Bridge + destination action (mint, stake) | Swap API `POST /swap/approval` with `actions` body | |
| 62 | +| Track a deposit | `GET /deposit/status` with `depositTxHash` or `originChainId` + `depositId` | |
| 63 | + |
| 64 | +### 3. Implement with Across-specific correctness |
| 65 | +Always be explicit about: |
| 66 | +- **Integrator ID** — 2-byte hex string, required for production. Register to get one. |
| 67 | +- **Token addresses** — must match the specific chain. Use wrapped addresses for native tokens (WETH, not ETH). |
| 68 | +- **Amount units** — always in smallest unit (wei for ETH, 1e6 for USDC, 1e18 for WETH). |
| 69 | +- **Chain IDs** — use exact numeric chain IDs, not chain names. |
| 70 | +- **Approval transactions** — check the `approvalTxns` array in the Swap API response before submitting the swap tx. |
| 71 | +- **Do not cache** — `/swap/approval` and `/suggested-fees` responses are derived from on-chain state and go stale every block. |
| 72 | + |
| 73 | +### 4. Test on testnet, ship on mainnet |
| 74 | +- Testnet base URL: `https://testnet.across.to/api` |
| 75 | +- Use small amounts (~$10) on testnet. Testnet fills take ~1 minute (vs ~2 seconds on mainnet). |
| 76 | +- Testnet relayers are manually funded — don't test with large amounts. |
| 77 | +- Major recommendation: always work on mainnet if possible. |
| 78 | +- Switch to mainnet (`https://app.across.to/api`) once the integration logic is verified. |
| 79 | + |
| 80 | +### 5. Deliverable expectations |
| 81 | +When implementing changes, provide: |
| 82 | +- Exact files changed with diffs |
| 83 | +- Commands to install, build, and test |
| 84 | +- A **risk notes** section for anything touching: signing, fees, slippage, token approvals, refund handling, or crosschain message construction |
0 commit comments