​

o1.exchange Plugin

[!IMPORTANT] Run Base MCP onboarding first (see SKILL.md). Authentication is pre-configured — no setup needed.

​

Overview

​

Auth

{
  "Authorization": "Bearer d1fa1477bd94e988185fca9d4bbae8d22ee5cafd45d6f9b6a43ba16a8b15f4d3",
  "Content-Type": "application/json"
}

​

Surface Routing

​

Endpoints

​

POST /order

{
  "networkId": 8453,
  "signerAddress": "<wallet address>",
  "tokenAddress": "<token contract address>",
  "uiAmount": "100",
  "direction": "buy",
  "slippageBps": 300,
  "mevProtection": true
}

{
  "success": true,
  "id": "<batch-id>",
  "transactions": [
    {
      "id": "<tx-id>",
      "unsigned": "0x02f8…<RLP-encoded transaction hex>",
      "permit2": {
        "eip712": {
          "domain": { },
          "types": { },
          "values": { }
        }
      }
    }
  ]
}

[!WARNING] unsigned is a raw RLP-encoded transaction hex string, not a structured object. You must RLP-decode it to extract the to, data, and value fields needed by send_calls. See the RLP decoding step below.

​

POST /order/complete

{
  "id": "<batch-id from /order>",
  "transactions": [
    {
      "id": "<tx-id>",
      "permit2": {
        "eip712": {
          "signature": "0x<permit2 signature>"
        }
      }
    }
  ]
}

{
  "success": true,
  "transactions": [
    {
      "hash": "0x…",
      "status": "pending",
      "tokenDelta": "…"
    }
  ]
}

​

RLP Decoding

[chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList]

1. If unsigned starts with 0x02, strip the 0x02 type prefix byte before RLP decoding (the remaining bytes are the RLP-encoded payload).
2. RLP-decode the payload into a list of fields.
3. Extract to (index 5), value (index 6), and data (index 7).
4. Convert to to a checksummed 0x-prefixed address. Convert value to a 0x-prefixed hex string (pass "0x0" if zero/empty). Pass data as the 0x-prefixed hex string.

[!NOTE] If the harness environment supports a library like ethers.js (Transaction.from(unsigned)) or Python rlp/eth_account, use that instead of manual decoding. The manual field-position approach is a fallback for LLM-driven decoding without library access.

​

Orchestration

​

Standard swap (no Permit2)

1. get_wallets → wallet address.
2. Confirm trade parameters with the user: token, amount, direction, slippage. See Risks & Warnings before proceeding with elevated slippage.
3. web_request POST https://api.o1.exchange/api/v2/order with auth headers and swap parameters.
4. Verify success: true in response.
5. RLP-decode each transactions[].unsigned hex string to extract to, data, and value. Map networkId to chain string (8453 → "base", 56 → "bsc").
6. send_calls(chain, calls) → approvalUrl + requestId.
7. Present the approval URL: Approve Transaction. In CLI harnesses, also auto-open the link. Do not approve on the user’s behalf.
8. After the user confirms approval, call get_request_status(requestId) once.

​

Permit2 swap (Base only)

1. Follow steps 1–4 of the standard swap.
2. For each transaction with permit2.eip712: use Base MCP sign (type eth_signTypedData_v4) to sign the EIP-712 typed data → user approves → retrieve the signature.
3. web_request POST https://api.o1.exchange/api/v2/order/complete with auth headers and the batch payload:
   {
     "id": "<batch-id from /order>",
     "transactions": [
       {
         "id": "<tx-id>",
         "permit2": {
           "eip712": {
             "signature": "0x<signature from step 2>"
           }
         }
       }
     ]
   }
   
4. Verify success: true. The server re-encodes the calldata with the actual Permit2 signature (supporting both EOA and smart-account signatures) and broadcasts through the private mempool relay with MEV protection.
5. Present the returned transactions[].hash to the user for tracking.

​

Submission

{
  "chain": "base",
  "calls": [
    {
      "to": "<decoded to>",
      "data": "<decoded data>",
      "value": "<decoded value>"
    }
  ]
}

• value is hex-encoded wei (e.g. "0x2386f26fc10000" = 0.01 ETH). Pass "0x0" if the decoded value is empty or zero.
• Only to, data, and value are needed — all other decoded fields (nonce, gas, chainId, etc.) are stripped.
• Chain string mapping: networkId 8453 → "base", 56 → "bsc".
• Preserve transaction ordering when multiple transactions are returned in the batch.
• MEV note: Transactions submitted via send_calls are broadcast through the public mempool. The mevProtection flag in the /order request does not provide MEV protection for this path. Only Permit2 swaps routed through /order/complete are broadcast via the private mempool relay.
• Follow the approval/polling flow in approval-mode.md.

​

Example Prompts

1. get_wallets → address.
2. web_request POST /order with networkId: 8453, signerAddress: <address>, tokenAddress: <token>, uiAmount: "100", direction: "buy", slippageBps: 300, mevProtection: true.
3. RLP-decode transactions[].unsigned → extract to, data, value → send_calls(chain="base", calls).
4. User approves → get_request_status(requestId).

1. get_wallets → address.
2. web_request POST /order with networkId: 8453, signerAddress: <address>, tokenAddress: <token>, uiAmount: "<amount>", direction: "sell", slippageBps: 300, mevProtection: true.
3. RLP-decode transactions[].unsigned → extract to, data, value → send_calls(chain="base", calls).
4. User approves → get_request_status(requestId).

1. get_wallets → address.
2. web_request POST /order with slippageBps: 100 (1%), mevProtection: true.
3. RLP-decode transactions[].unsigned → extract to, data, value → send_calls(chain="base", calls).
4. User approves → get_request_status(requestId).

1. get_wallets → address.
2. web_request POST /order with poolAddress: <pool>, direction: "buy", slippageBps: 300, mevProtection: true.
3. RLP-decode transactions[].unsigned → extract to, data, value → send_calls(chain="base", calls).
4. User approves → get_request_status(requestId).

​

Risks & Warnings

• Slippage — trades can fill materially worse than expected. Default to 300 bps (3%). For volatile or low-liquidity tokens, the user may need 500–1000 bps. Warn before submitting slippage above 500 bps; require explicit confirmation above 1000 bps. Never silently increase slippage.
• Irreversible — onchain swaps cannot be undone once confirmed. Always present the trade parameters (token, amount, direction, slippage) to the user and require explicit confirmation before calling send_calls.
• Low liquidity — arbitrary tokens and pool-targeted trades (poolAddress) may have thin liquidity, leading to high price impact and poor fills. Warn the user when trading tokens without well-known liquidity or when targeting a specific pool. Consider suggesting smaller trade sizes or wider slippage tolerance.
• MEV exposure — standard swaps submitted via send_calls go through the public mempool and are not MEV-protected, even if mevProtection: true was set in the /order request. Only Permit2 swaps routed through /order/complete receive private mempool relay protection.

​

Notes

• Network IDs: 8453 = Base, 56 = BSC. Solana (1399811149) is supported by the o1.exchange API but not by Base MCP.
• Slippage guidance: Normal 300 bps (3%); volatile tokens 500–1000 bps (5–10%); increase for large trades.
• MEV protection: mevProtection: true requests MEV protection from the API. This only takes effect when submitting through /order/complete (Permit2 flow). Standard swaps via send_calls go through the public mempool regardless. Still recommended to set true on all /order requests.
• Permit2 signatures: Do not perform client-side replacement of the signature placeholder in unsigned.data. Submit the Permit2 signature to /order/complete for server-side re-encoding, which correctly handles both EOA (65-byte) and smart-account (variable-length ERC-1271/6492) signatures.
• Quote token: quoteTokenAddress specifies which stablecoin to quote against (Base only). Omit to use the default.
• Pool selection: poolAddress targets a specific liquidity pool. Omit to let the API choose the best route.
• API token: A shared token is pre-configured for Base MCP Plugin users — no generation or setup required.