@orbs-network/spot-skill 2.4.0

package/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: spot-advanced-swap-orders
+description: Use for gasless non-custodial EVM market, limit, TWAP, stop-loss, take-profit, delayed-start orders.
+---
+
+# Spot Advanced Swap Orders
+
+Use this for gasless market swaps and advanced orders on supported EVM chains.
+Choose this skill when a user wants market, limit, TWAP, stop-loss, take-profit, or delayed-start execution, or needs to prepare, sign, submit, query, or cancel one of those orders.
+Supply chain, token addresses, chunk sizing, timing, and optional price constraints.
+The helper turns that into approval calldata, EIP-712 typed data, relay-ready submit payloads, and query/cancel guidance,
+while decentralized, non-custodial, oracle-protected, immutable, audited, battle-tested contracts handle execution.
+
+## Config
+
+```json
+{
+  "references": [
+    "references/01-quickstart.md",
+    "references/02-params.md",
+    "references/03-sign.md",
+    "references/04-patterns.md"
+  ],
+  "scripts": [
+    "scripts/order.js"
+  ],
+  "assets": [
+    "assets/token-addressbook.md",
+    "assets/repermit.skeleton.json",
+    "assets/web3-sign-and-submit.example.js"
+  ],
+  "runtime": {
+    "url": "https://agents-sink.orbs.network",
+    "contracts": {
+      "zero": "0x0000000000000000000000000000000000000000",
+      "repermit": "0x00002a9C4D9497df5Bd31768eC5d30eEf5405000",
+      "reactor": "0x000000b33fE4fB9d999Dd684F79b110731c3d000",
+      "executor": "0x000642A0966d9bd49870D9519f76b5cf823f3000"
+    },
+    "chains": {
+      "1": {
+        "name": "Ethereum",
+        "adapter": "0xC1bB4d5071Fe7109ae2D67AE05826A3fe9116cfc"
+      },
+      "56": {
+        "name": "BNB Chain",
+        "adapter": "0x67Feba015c968c76cCB2EEabf197b4578640BE2C"
+      },
+      "137": {
+        "name": "Polygon",
+        "adapter": "0x75A3d70Fa6d054d31C896b9Cf8AB06b1c1B829B8"
+      },
+      "146": {
+        "name": "Sonic",
+        "adapter": "0x58fD209C81D84739BaD9c72C082350d67E713EEa"
+      },
+      "8453": {
+        "name": "Base",
+        "adapter": "0x5906C4dD71D5afFe1a8f0215409E912eB5d593AD"
+      },
+      "42161": {
+        "name": "Arbitrum One",
+        "adapter": "0x026B8977319F67078e932a08feAcB59182B5380f"
+      },
+      "43114": {
+        "name": "Avalanche",
+        "adapter": "0x4F48041842827823D3750399eCa2832fC2E29201"
+      },
+      "59144": {
+        "name": "Linea",
+        "adapter": "0x55E4da2cd634729064bEb294EC682Dc94f5c3f24"
+      }
+    }
+  }
+}
+```
+
+## Distribution
+
+This skill ships from the canonical repository [`orbs-network/spot`](https://github.com/orbs-network/spot) across four AI-agent distribution surfaces:
+
+1. Self-contained package file [`SKILL.md`](SKILL.md), plus the local `references/`, `assets/`, and `scripts/` directories.
+2. Hosted raw files under [`https://orbs-network.github.io/spot/`](https://orbs-network.github.io/spot/), with `skill/` paths as the canonical hosted bundle.
+3. The npm package `@orbs-network/spot-skill`, which installs this self-contained bundle as published.
+4. The stdio MCP adapter `spot-mcp`, published in `mcp/server.json` as `io.github.orbs-network/spot`.
+
+The checked-in `mcp/server.json` registry metadata is derived from [`SKILL.md`](SKILL.md) plus package metadata, so MCP publishing stays aligned.
+
+Outside tools should treat [`SKILL.md`](SKILL.md) as both the entrypoint and the machine-readable metadata source. Frontmatter provides slug and description, and the `## Config` block provides the bundled runtime metadata.
+
+## Workflow
+
+1. Read [references/01-quickstart.md](references/01-quickstart.md) for the minimum end-to-end flow.
+2. Read [references/02-params.md](references/02-params.md) when you need field semantics, defaults, units, or validation rules.
+3. Read [references/03-sign.md](references/03-sign.md) for signing, signature formats, and direct onchain cancel.
+4. Read [references/04-patterns.md](references/04-patterns.md) to map user intent into market, limit, stop-loss, take-profit, delayed, or chunked orders.
+5. Optional helper for token lookup: [assets/token-addressbook.md](assets/token-addressbook.md).
+6. Use [assets/repermit.skeleton.json](assets/repermit.skeleton.json) when you need the raw RePermit witness typed-data skeleton.
+7. Use [assets/web3-sign-and-submit.example.js](assets/web3-sign-and-submit.example.js) for a browser or injected-provider signing and submit example.
+8. Inspect the frontmatter and `## Config` JSON block in [`SKILL.md`](SKILL.md) for machine-readable metadata, the live supported-chain matrix, sink URL, and runtime contract addresses.
+9. Use only [scripts/order.js](scripts/order.js) to prepare, submit, query, and watch orders.
+
+## Guardrails
+
+1. Supported chains and runtime addresses live in the `## Config` JSON block in [`SKILL.md`](SKILL.md).
+2. Use only the provided [scripts/order.js](scripts/order.js). Do not send typed data or signatures anywhere else.
+3. Use [references/02-params.md](references/02-params.md) as the authoritative source for native-asset rules and for `output.limit` / trigger units.
+4. Detailed order behavior, parameter rules, signing rules, and order-shape guidance live in the reference files above.
+
+## Commands
+
+1. Prepare: `node scripts/order.js prepare --params <params.json|-> [--out <prepared.json>]`
+2. Submit: `node scripts/order.js submit --prepared <prepared.json|-> --signature <0x...|json>`
+3. Submit variants: `--signature-file <file|->` or `--r <0x...> --s <0x...> --v <0x...>`
+4. Query: `node scripts/order.js query --swapper <0x...>` or `--hash <0x...>`
+5. Watch: `node scripts/order.js watch --hash <0x...> [--interval <seconds>] [--timeout <seconds>]`

package/assets/repermit.skeleton.json

@@ -0,0 +1,195 @@
+{
+  "domain": {
+    "name": "RePermit",
+    "version": "1",
+    "chainId": "<CHAINID>",
+    "verifyingContract": "<REPERMIT>"
+  },
+  "primaryType": "RePermitWitnessTransferFrom",
+  "types": {
+    "RePermitWitnessTransferFrom": [
+      {
+        "name": "permitted",
+        "type": "TokenPermissions"
+      },
+      {
+        "name": "spender",
+        "type": "address"
+      },
+      {
+        "name": "nonce",
+        "type": "uint256"
+      },
+      {
+        "name": "deadline",
+        "type": "uint256"
+      },
+      {
+        "name": "witness",
+        "type": "Order"
+      }
+    ],
+    "Exchange": [
+      {
+        "name": "adapter",
+        "type": "address"
+      },
+      {
+        "name": "ref",
+        "type": "address"
+      },
+      {
+        "name": "share",
+        "type": "uint32"
+      },
+      {
+        "name": "data",
+        "type": "bytes"
+      }
+    ],
+    "Input": [
+      {
+        "name": "token",
+        "type": "address"
+      },
+      {
+        "name": "amount",
+        "type": "uint256"
+      },
+      {
+        "name": "maxAmount",
+        "type": "uint256"
+      }
+    ],
+    "Order": [
+      {
+        "name": "reactor",
+        "type": "address"
+      },
+      {
+        "name": "executor",
+        "type": "address"
+      },
+      {
+        "name": "exchange",
+        "type": "Exchange"
+      },
+      {
+        "name": "swapper",
+        "type": "address"
+      },
+      {
+        "name": "nonce",
+        "type": "uint256"
+      },
+      {
+        "name": "start",
+        "type": "uint256"
+      },
+      {
+        "name": "deadline",
+        "type": "uint256"
+      },
+      {
+        "name": "chainid",
+        "type": "uint256"
+      },
+      {
+        "name": "exclusivity",
+        "type": "uint32"
+      },
+      {
+        "name": "epoch",
+        "type": "uint32"
+      },
+      {
+        "name": "slippage",
+        "type": "uint32"
+      },
+      {
+        "name": "freshness",
+        "type": "uint32"
+      },
+      {
+        "name": "input",
+        "type": "Input"
+      },
+      {
+        "name": "output",
+        "type": "Output"
+      }
+    ],
+    "Output": [
+      {
+        "name": "token",
+        "type": "address"
+      },
+      {
+        "name": "limit",
+        "type": "uint256"
+      },
+      {
+        "name": "triggerLower",
+        "type": "uint256"
+      },
+      {
+        "name": "triggerUpper",
+        "type": "uint256"
+      },
+      {
+        "name": "recipient",
+        "type": "address"
+      }
+    ],
+    "TokenPermissions": [
+      {
+        "name": "token",
+        "type": "address"
+      },
+      {
+        "name": "amount",
+        "type": "uint256"
+      }
+    ]
+  },
+  "message": {
+    "permitted": {
+      "token": "<INTOKEN>",
+      "amount": "<INTOTALAMOUNT>"
+    },
+    "spender": "<REACTOR>",
+    "nonce": "<NONCE>",
+    "deadline": "<DEADLINE>",
+    "witness": {
+      "reactor": "<REACTOR>",
+      "executor": "<EXECUTOR>",
+      "exchange": {
+        "adapter": "<ADAPTER>",
+        "ref": "<REFERRER>",
+        "share": "<REFSHAREBPS>",
+        "data": "<ADAPTER_USER_DATA>"
+      },
+      "swapper": "<SWAPPER>",
+      "nonce": "<NONCE>",
+      "start": "<START>",
+      "deadline": "<DEADLINE>",
+      "chainid": "<CHAINID>",
+      "exclusivity": "<EXCLUSIVITYBPS>",
+      "epoch": "<EPOCHSECONDS>",
+      "slippage": "<SLIPPAGEBPS>",
+      "freshness": "<FRESHNESSSECONDS>",
+      "input": {
+        "token": "<INTOKEN>",
+        "amount": "<INCHUNKAMOUNT>",
+        "maxAmount": "<INTOTALAMOUNT>"
+      },
+      "output": {
+        "token": "<OUTTOKEN>",
+        "limit": "<OUTAMOUNTMIN>",
+        "triggerLower": "<OUTAMOUNTTRIGGERLOWER>",
+        "triggerUpper": "<OUTAMOUNTTRIGGERUPPER>",
+        "recipient": "<RECIPIENT>"
+      }
+    }
+  }
+}

package/assets/token-addressbook.md

@@ -0,0 +1,97 @@
+# Common Token Addressbook
+
+## Ethereum (`1`)
+
+1. `weth`: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
+2. `wbtc`: `0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599`
+3. `usdc`: `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
+4. `usdt`: `0xdAC17F958D2ee523a2206206994597C13D831ec7`
+5. `dai`: `0x6B175474E89094C44Da98b954EedeAC495271d0F`
+6. `lusd`: `0x5f98805A4E8be255a32880FDeC7F6728C6568bA0`
+7. `orbs`: `0xff56Cc6b1E6dEd347aA0B7676C85AB0B3D08B0FA`
+
+## BNB Chain (`56`)
+
+1. `wbnb`: `0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c`
+2. `btcb`: `0x7130d2A12B9BCbFAe4f2634d864A1Ee1Ce3Ead9c`
+3. `wbtc`: `0x0555e30da8f98308edb960aa94c0db47230d2b9c`
+4. `usdc`: `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d`
+5. `usdt`: `0x55d398326f99059fF775485246999027B3197955`
+6. `usd1`: `0x8d0d000ee44948fc98c9b98a4fa4921476f08b0d`
+7. `dai`: `0x1AF3F329e8BE154074D8769D1FFa4eE058B1DBc3`
+8. `busd`: `0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56`
+9. `weth`: `0x2170Ed0880ac9A755fd29B2688956BD959F933F8`
+10. `orbs`: `0x43a8cab15D06d3a5fE5854D714C37E7E9246F170`
+
+## Polygon (`137`)
+
+1. `wmatic`: `0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270`
+2. `wbtc`: `0x1BFD67037B42Cf73acF2047067bd4F2C47D9BfD6`
+3. `usdc`: `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`
+4. `usdc.e`: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
+5. `usdt`: `0xc2132D05D31c914a87C6611C10748AEb04B58e8F`
+6. `dai`: `0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063`
+7. `weth`: `0x7ceb23fd6bc0add59e62ac25578270cff1b9f619`
+8. `orbs`: `0x614389EaAE0A6821DC49062D56BDA3d9d45Fa2ff`
+
+## Arbitrum One (`42161`)
+
+1. `weth`: `0x82af49447d8a07e3bd95bd0d56f35241523fbab1`
+2. `wbtc`: `0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f`
+3. `usdc`: `0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
+4. `usdt`: `0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9`
+5. `dai`: `0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1`
+6. `arb`: `0x912CE59144191C1204E64559FE8253a0e49E6548`
+7. `orbs`: `0xf3C091ed43de9c270593445163a41A876A0bb3dd`
+
+## Optimism (`10`)
+
+1. `weth`: `0x4200000000000000000000000000000000000006`
+2. `wbtc`: `0x68f180fcCe6836688e9084f035309E29Bf0A2095`
+3. `usdc`: `0x7F5c764cBc14f9669B88837ca1490cCa17c31607`
+4. `usdt`: `0x94b008aA00579c1307B0EF2c499aD98a8ce58e58`
+5. `dai`: `0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1`
+6. `op`: `0x4200000000000000000000000000000000000042`
+
+## Avalanche (`43114`)
+
+1. `wavax`: `0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7`
+2. `wbtc`: `0x50b7545627a5162F82A992c33b87aDc75187B218`
+3. `usdc`: `0xA7D7079b0FEaD91F3e65f86E8915Cb59c1a4C664`
+4. `usdt`: `0xc7198437980c041c805A1EDcbA50c1Ce5db95118`
+5. `dai`: `0xd586E7F844cEa2F87f50152665BCbc2C279D8d70`
+6. `weth`: `0x49D5c2BdFfac6CE2BFdB6640F4F80f226bc10bAB`
+7. `orbs`: `0x340fE1D898ECCAad394e2ba0fC1F93d27c7b717A`
+
+## Base (`8453`)
+
+1. `weth`: `0x4200000000000000000000000000000000000006`
+2. `usdc`: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+3. `dai`: `0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb`
+4. `cbbtc`: `0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf`
+
+## Mantle (`5000`)
+
+1. `wmnt`: `0x78c1b0C915c4FAA5FffA6CAbf0219DA63d7f4cb8`
+2. `weth`: `0xdeaddeaddeaddeaddeaddeaddeaddeaddead1111`
+3. `usdc`: `0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9`
+4. `usdt`: `0x201eba5cc46D216Ce6DC03F6a759e8E766e956Ae`
+5. `usdt0`: `0x779Ded0c9e1022225f8E0630b35a9b54bE713736`
+
+## Linea (`59144`)
+
+1. `weth`: `0xe5D7C2a44FfDDf6b295A15c148167daaAf5Cf34f`
+2. `wbtc`: `0x3aAB2285ddcDdaD8edf438C1bAB47e1a9D05a9b4`
+3. `usdc`: `0x176211869cA2b568f2A7D4EE941E073a821EE1ff`
+4. `usdt`: `0xA219439258ca9da29E9Cc4cE5596924745e12B93`
+5. `dai`: `0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5`
+
+## Sonic (`146`)
+
+1. `ws`: `0x039e2fB66102314Ce7b64Ce5Ce3E5183bc94aD38`
+2. `wbtc`: `0x0555E30da8f98308EdB960aa94C0Db47230d2B9c`
+3. `weth`: `0x50c42dEAcD8Fc9773493ED674b675bE577f2634b`
+4. `usdc`: `0x29219dd400f2Bf60E5a23d13Be72B486D4038894`
+5. `usdt`: `0x6047828dc181963ba44974801FF68e538dA5eaF9`
+6. `sfc`: `0xFC00FACE00000000000000000000000000000000`
+

package/assets/web3-sign-and-submit.example.js

@@ -0,0 +1,111 @@
+// Example only. This flow uses eth_signTypedData_v4 via an injected provider,
+// but any framework that signs the same prepared.typedData payload is valid.
+
+import Web3 from "web3";
+
+const DEPOSIT_DATA = "0xd0e30db0";
+const ERC20_ABI = [
+  {
+    constant: true,
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+    ],
+    name: "allowance",
+    outputs: [{ name: "", type: "uint256" }],
+    type: "function",
+  },
+];
+
+export async function approveSignAndSubmitOrder({
+  prepared,
+  account,
+  provider = window.ethereum,
+  wrappedNative,
+  nativeInputAmount,
+  sendApproval = true,
+}) {
+  const web3 = new Web3(provider);
+  const normalizedAccount = account.toLowerCase();
+  const expectedSigner = prepared.signing.signer.toLowerCase();
+
+  // The EIP-712 signer must be the same address that created the order.
+  if (normalizedAccount !== expectedSigner) {
+    throw new Error(
+      `signer mismatch: expected ${prepared.signing.signer}, got ${account}`
+    );
+  }
+
+  // Native input is not supported by the order itself.
+  // If the input starts as the chain's native asset, wrap it to WNATIVE first.
+  if (
+    nativeInputAmount != null &&
+    nativeInputAmount !== "0" &&
+    nativeInputAmount !== "0x0"
+  ) {
+    if (!wrappedNative) {
+      throw new Error("wrappedNative is required when nativeInputAmount is set");
+    }
+
+    await web3.eth.sendTransaction({
+      from: account,
+      to: wrappedNative,
+      data: DEPOSIT_DATA,
+      value: nativeInputAmount,
+    });
+  }
+
+  if (prepared.approval && sendApproval) {
+    // The skill helper is RPC-agnostic, so the caller should use its own
+    // provider access to avoid resending the same infinite approval.
+    const token = new web3.eth.Contract(ERC20_ABI, prepared.approval.tx.to);
+    const allowance = BigInt(
+      await token.methods
+        .allowance(account, prepared.approval.spender)
+        .call()
+    );
+
+    if (allowance < BigInt(prepared.approval.amount)) {
+      await web3.eth.sendTransaction({
+        from: account,
+        to: prepared.approval.tx.to,
+        data: prepared.approval.tx.data,
+        value: prepared.approval.tx.value,
+      });
+    }
+  }
+
+  // This example uses eth_signTypedData_v4, but any equivalent EIP-712 signer works.
+  const signature = await provider.request({
+    method: "eth_signTypedData_v4",
+    params: [account, JSON.stringify(prepared.typedData)],
+  });
+
+  // Submit the order payload plus the returned signature to the relay endpoint.
+  const response = await fetch(prepared.submit.url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      ...prepared.submit.body,
+      signature,
+    }),
+  });
+
+  const text = await response.text();
+  let body;
+
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+
+  return {
+    ok: response.ok,
+    status: response.status,
+    signature,
+    body,
+  };
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@orbs-network/spot-skill",
+    "version": "2.4.0",
+    "description": "Use for gasless non-custodial EVM market, limit, TWAP, stop-loss, take-profit, delayed-start orders.",
+    "homepage": "https://orbs-network.github.io/spot/",
+    "bugs": {
+        "url": "https://github.com/orbs-network/spot/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/orbs-network/spot.git",
+        "directory": "skill"
+    },
+    "license": "MIT",
+    "author": "danielz@orbs.com",
+    "engines": {
+        "node": ">=18"
+    },
+    "files": [
+        "SKILL.md",
+        "references/01-quickstart.md",
+        "references/02-params.md",
+        "references/03-sign.md",
+        "references/04-patterns.md",
+        "assets/token-addressbook.md",
+        "assets/repermit.skeleton.json",
+        "assets/web3-sign-and-submit.example.js",
+        "scripts/order.js"
+    ]
+}

package/references/01-quickstart.md

@@ -0,0 +1,12 @@
+# Quickstart
+
+1. Required fields: `chainId`, `swapper`, `input.token`, `input.amount`, `output.token`.
+2. Choose the intended order shape before preparing: market, limit, stop-loss, take-profit, delayed-start, or chunked/TWAP.
+3. Prepare the order with the helper.
+4. If approval is needed, send `prepared.approval.tx` to approve `RePermit`.
+5. The skill helper does not read allowance onchain. The calling agent or app should use its own RPC or provider access to compare the current ERC-20 allowance against `prepared.approval.amount`, send that infinite approval only when allowance is lower, and then leave the infinite approval in place with no reset.
+6. Sign `prepared.typedData` as the `swapper`.
+7. Submit the signed order.
+8. Query the order by `swapper` or `hash`.
+9. Watch until terminal state. Default polling is every 5 seconds, timeout `0` means no timeout, and transient network errors are retried automatically.
+10. When measuring a fill onchain, sum both transfers to the swapper: the main fill and the surplus refund. Measuring only the main fill undercounts actual output by up to the slippage tolerance.

package/references/02-params.md

@@ -0,0 +1,39 @@
+# Params
+
+Use this file for field semantics, defaults, units, and validation.
+
+1. Required: `chainId`, `swapper`, `input.token`, `input.amount`, `output.token`.
+2. Optional: `input.maxAmount`, `nonce`, `start`, `deadline`, `epoch`, `slippage`, `output.limit`, `output.triggerLower`, `output.triggerUpper`, `output.recipient`.
+3. `input.amount` is the fixed per-chunk size. `input.maxAmount` is the total requested size. If omitted, it defaults to `input.amount`. If it is not divisible by `input.amount`, the helper rounds it down to a whole number of chunks.
+4. `output.limit`, `output.triggerLower`, and `output.triggerUpper` are output-token amounts per chunk, encoded in the output token's decimals.
+5. Future `start` delays the first fill. `epoch` is the delay between chunks, but it is not exact: each chunk can fill anywhere inside its epoch window, only once. Large `epoch` is not a delayed order by itself.
+6. Chunked orders should use `epoch > 0`; with `epoch = 0`, only the first chunk can fill.
+7. Defaults:
+   - `input.maxAmount = input.amount`
+   - `nonce = now`
+   - `start = now`
+   - `epoch = 0` for single orders, `60` for chunked orders
+   - `deadline = start + 300 + chunkCount * epoch`
+   - `slippage = 500`
+   - `output.limit = 0`
+   - `output.recipient = swapper`
+8. Higher slippage is still protected by oracle pricing and offchain executors.
+9. `output.recipient` is dangerous to change away from `swapper`.
+10. Native input is not supported. Wrap to WNATIVE first. Native output, including "back to native" orders, is supported directly with `output.token = 0x0000000000000000000000000000000000000000`.
+11. Example:
+
+```json
+{
+  "chainId": 42161,
+  "swapper": "0x1111111111111111111111111111111111111111",
+  "input": {
+    "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    "amount": "1000000"
+  },
+  "output": {
+    "token": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
+    "limit": "0"
+  },
+  "epoch": 3600
+}
+```

package/references/03-sign.md

@@ -0,0 +1,6 @@
+# Sign And Submit
+
+1. Sign `prepared.typedData` with any EIP-712-capable wallet or library. The signer must equal `swapper`. `eth_signTypedData_v4` is only one example.
+2. Submit with `--prepared <prepared.json|->` and exactly one signature mode: `--signature <0x...|json>`, `--signature-file <sig.txt|sig.json|->`, or `--r <0x...> --s <0x...> --v <0x...>`.
+3. The helper accepts a full 65-byte signature, a JSON string, or JSON/object `r/s/v`.
+4. Cancel trustlessly onchain by calling `RePermit.cancel([digest])` as the swapper for the signed RePermit digest.

package/references/04-patterns.md

@@ -0,0 +1,12 @@
+# Order Patterns
+
+1. Market swap: `input.amount = input.maxAmount`, `output.limit = 0`.
+2. Limit order: `input.amount = input.maxAmount`, `output.limit > 0`.
+3. Stop-loss or take-profit: set `output.triggerLower` for stop-loss and/or `output.triggerUpper` for take-profit.
+4. Delayed order: set future `start`.
+5. Chunked or TWAP-style: set `input.amount < input.maxAmount`.
+6. Time-spaced chunked order: set `epoch > 0`. For example, `epoch = 60` means one chunk can fill once anywhere inside each 60-second epoch window.
+7. `N chunks`: use one TWAP order instead of manually submitting `N` separate orders. Use `input.maxAmount` as the requested total amount, set `input.amount = floor(total / N)`, and accept any rounded-down remainder as dust.
+8. If timing is omitted for a chunked or TWAP order, `epoch` defaults to `60`. Single orders default to `0`.
+9. Native output or back to native exposure: set `output.token = 0x0000000000000000000000000000000000000000`.
+10. Best execution and oracle protection apply regardless of `output.limit`.