swap:quote

swap family

mcp

Price a swap of any coin to any coin, or into Hyperliquid; live, get the deposit address your OWN wallet sends to — ONE never holds funds. Dry by default

Effect: ask; Awaits an outcome — the call returns the response below.
Caller: public; The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost: free; What one call costs, so you can budget before acting.
Reversible: yes; The effect can be undone by a later call.
Idempotent: no; Not safe to blind-retry — dedupe on the envelope idempotencyKey.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code

Codex

Cursor

Gemini CLI

Claude Desktop

ChatGPT

curl -X POST https://one.ie/api/ask/swap:quote \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "from": "USDC@base", "to": "hl", "amount": "10" }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

from string required What you pay with, as an alias: BTC, SOL, SUI, USDC@sui, ETH@ethereum, ETH@base, ETH@arbitrum, USDC@ethereum, USDC@base, USDC@arbitrum, USDC@solana, USDT@ethereum, USDT0@arbitrum. A symbol on several chains must name its chain. An unknown alias returns the whole table
to string required What you receive, as an alias; 'hyperliquid' or 'hl' = USDC in your Hyperliquid perps account. Bare ETH→ethereum, USDC→base, USDT→ethereum
amount string required Decimal string in the FROM asset (in the TO asset when exact is 'out'), e.g. '0.01' — never a number; converted to base units exactly
exact in | out optional 'in' (default): spend exactly amount · 'out': receive exactly amount; slippage applies to the input
dry boolean optional true (default) = price only, no deposit address · false = mint a live deposit address; needs a signed-in person or a world key
recipient string optional Destination address. Absent = your own address on the destination chain. Someone else's needs toOther:true
refundTo string optional Only to choose among YOUR OWN source-chain addresses (the options of ambiguous_address). Absent = your one owned address. Someone else's is refused (refund_not_yours); toOther never applies
toOther boolean optional true = recipient is deliberately someone else's; echoed back. A person's session only — an agent key is refused. Never applies to the refund address
slippageBps number optional Max slippage in basis points, an integer 1–500; default 100 (1%). Out of range is refused bad_slippage
net string optional 1Click is mainnet only: 'testnet' is refused by name (oneclick_mainnet_only), never answered with mainnet

Response

What comes back from the call.

ok boolean true = a quote; false = a named refusal in error
error string unknown_asset · ambiguous_asset · not_a_destination · hyperliquid_origin_unsupported · bad_amount · bad_slippage · same_asset · oneclick_mainnet_only · sign_in_required · platform_cannot_swap · live_quote_limit · refund_address_unknown · refund_not_yours · ambiguous_address · recipient_address_unknown · recipient_not_yours · toOther_needs_person · destination_unsignable · refund_unsignable · recipient_must_be_named · refund_must_be_named · recipient_invalid · refund_invalid · amount_too_low · amount_too_small_for_fees · exact_out_needs_funded_account · no_liquidity · asset_unsupported · memo_unsupported · quote_refused · oneclick_timeout · oneclick_unavailable · oneclick_error
detail string 1Click's own message on an upstream refusal, verbatim
options string[] ambiguous_asset: aliases to choose from · ambiguous_address: your addresses to choose from (pass one as recipient or refundTo)
assets object[] unknown_asset: the whole table (never paged)
minimum string amount_too_low: the minimum 1Click named, as a decimal in FROM, only when its unit is known; otherwise read detail
network string Always 'mainnet' — real chains, real money
dry boolean Echo: true = price only
from object Resolved origin
to object Resolved destination
route object How the coins get there
depositAddress string Live only: the key swap:get takes. Send exactly send.amount here — verify it with 1Click first
amountIn string Decimal you send
minAmountIn string exact 'out': lowest input accepted, decimal
amountOut string Decimal you receive (withdraw fee already taken)
minAmountOut string Decimal floor after slippage
amountInUsd string USD value in, per 1Click
amountOutUsd string USD value out, per 1Click
costUsd string amountInUsd − amountOutUsd, plus a possible Hyperliquid activation when it applies
fees object[] Every fee read from the live quote — none hardcoded
timeEstimateSec number Seconds after the deposit confirms
refundAfter string ISO: if not filled by now, refunds begin. Never send after this
addressExpires string Live only, ISO: deposit address goes inactive
quotedAt string 1Click's timestamp — clients correct their clock skew with it before the deadline check
recipient string Where the coins go — echoed
refundTo string Where a refund goes — always your own address on the source chain
ownership object Whose addresses these are, and how ONE knows
send object Live only: the exact send instruction — plain transfer, self-custody wallet, no bridge
hyperliquid object Hyperliquid destination with YOUR recipient only — absent for placeholders
keyed boolean true = ONE's partner key was used (live only); false = keyless fee schedule
warnings string[] poor_rate:<pct kept> · possible_activation_fee · external_send · jwt_rejected · app_fee_off · amount_too_small_for_fees (dry only; live refuses) · exact_out_needs_funded_account (dry only; live refuses)
link string Absolute one.ie URL: dry = a prefilled /swap form a person can sign from · live = its status page
next string One sentence: what to do now. An agent cannot sign — give the person the link, or the exact send line

Traffic

Every call to swap:quote, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names swap:quote, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

UI 1

one.ie/web/src/components/swap/SwapPage.tsx:243

API route 3

one.ie/web/src/lib/receiver-index.generated.ts:376
one.ie/web/src/lib/resolvers/swap.ts:2
one.ie/web/src/lib/swap/client.ts:564

CLI 1

packages/cli/src/swap.ts:146

Docs 1

one.ie/web/src/content/docs/wallets.md:181

→

Answered by

swap:quote one.ie/web/src/lib/resolvers/swap.ts:506 Dispatched through POST /api/ask/swap:quote, after the envelope validates the payload.

swap family · 1 more

swap:get

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "What you pay with, as an alias: BTC, SOL, SUI, USDC@sui, ETH@ethereum, ETH@base, ETH@arbitrum, USDC@ethereum, USDC@base, USDC@arbitrum, USDC@solana, USDT@ethereum, USDT0@arbitrum. A symbol on several chains must name its chain. An unknown alias returns the whole table"
    },
    "to": {
      "type": "string",
      "description": "What you receive, as an alias; 'hyperliquid' or 'hl' = USDC in your Hyperliquid perps account. Bare ETH→ethereum, USDC→base, USDT→ethereum"
    },
    "amount": {
      "type": "string",
      "description": "Decimal string in the FROM asset (in the TO asset when exact is 'out'), e.g. '0.01' — never a number; converted to base units exactly"
    },
    "exact": {
      "description": "'in' (default): spend exactly amount · 'out': receive exactly amount; slippage applies to the input",
      "type": "string",
      "enum": [
        "in",
        "out"
      ]
    },
    "dry": {
      "description": "true (default) = price only, no deposit address · false = mint a live deposit address; needs a signed-in person or a world key",
      "type": "boolean"
    },
    "recipient": {
      "description": "Destination address. Absent = your own address on the destination chain. Someone else's needs toOther:true",
      "type": "string"
    },
    "refundTo": {
      "description": "Only to choose among YOUR OWN source-chain addresses (the options of ambiguous_address). Absent = your one owned address. Someone else's is refused (refund_not_yours); toOther never applies",
      "type": "string"
    },
    "toOther": {
      "description": "true = recipient is deliberately someone else's; echoed back. A person's session only — an agent key is refused. Never applies to the refund address",
      "type": "boolean"
    },
    "slippageBps": {
      "description": "Max slippage in basis points, an integer 1–500; default 100 (1%). Out of range is refused bad_slippage",
      "type": "number"
    },
    "net": {
      "description": "1Click is mainnet only: 'testnet' is refused by name (oneclick_mainnet_only), never answered with mainnet",
      "type": "string"
    }
  },
  "required": [
    "from",
    "to",
    "amount"
  ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "true = a quote; false = a named refusal in error"
    },
    "error": {
      "description": "unknown_asset · ambiguous_asset · not_a_destination · hyperliquid_origin_unsupported · bad_amount · bad_slippage · same_asset · oneclick_mainnet_only · sign_in_required · platform_cannot_swap · live_quote_limit · refund_address_unknown · refund_not_yours · ambiguous_address · recipient_address_unknown · recipient_not_yours · toOther_needs_person · destination_unsignable · refund_unsignable · recipient_must_be_named · refund_must_be_named · recipient_invalid · refund_invalid · amount_too_low · amount_too_small_for_fees · exact_out_needs_funded_account · no_liquidity · asset_unsupported · memo_unsupported · quote_refused · oneclick_timeout · oneclick_unavailable · oneclick_error",
      "type": "string"
    },
    "detail": {
      "description": "1Click's own message on an upstream refusal, verbatim",
      "type": "string"
    },
    "options": {
      "description": "ambiguous_asset: aliases to choose from · ambiguous_address: your addresses to choose from (pass one as recipient or refundTo)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "assets": {
      "description": "unknown_asset: the whole table (never paged)",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "description": "Canonical alias, e.g. USDC@base"
          },
          "chain": {
            "type": "string",
            "description": "ethereum | base | arbitrum | solana | sui | bitcoin | hyperliquid"
          },
          "symbol": {
            "type": "string",
            "description": "Ticker"
          },
          "assetId": {
            "type": "string",
            "description": "1Click asset id this alias resolves to"
          },
          "decimals": {
            "type": "number",
            "description": "Base-unit decimals"
          },
          "contract": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "EVM contract or Sui coin type; null for a native coin"
          },
          "signer": {
            "type": "string",
            "description": "browser = ONE's in-browser key can send it · external = send from any wallet to the deposit address · none = quote only"
          },
          "origin": {
            "type": "boolean",
            "description": "Can be swapped FROM (live)"
          },
          "destination": {
            "type": "boolean",
            "description": "Can be swapped TO"
          }
        },
        "required": [
          "alias",
          "chain",
          "symbol",
          "assetId",
          "decimals",
          "contract",
          "signer",
          "origin",
          "destination"
        ]
      }
    },
    "minimum": {
      "description": "amount_too_low: the minimum 1Click named, as a decimal in FROM, only when its unit is known; otherwise read detail",
      "type": "string"
    },
    "network": {
      "type": "string",
      "description": "Always 'mainnet' — real chains, real money"
    },
    "dry": {
      "description": "Echo: true = price only",
      "type": "boolean"
    },
    "from": {
      "description": "Resolved origin",
      "type": "object",
      "properties": {
        "alias": {
          "type": "string",
          "description": "Canonical alias, e.g. USDC@base"
        },
        "chain": {
          "type": "string",
          "description": "ethereum | base | arbitrum | solana | sui | bitcoin | hyperliquid"
        },
        "symbol": {
          "type": "string",
          "description": "Ticker"
        },
        "assetId": {
          "type": "string",
          "description": "1Click asset id this alias resolves to"
        },
        "decimals": {
          "type": "number",
          "description": "Base-unit decimals"
        },
        "contract": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "EVM contract or Sui coin type; null for a native coin"
        },
        "signer": {
          "type": "string",
          "description": "browser = ONE's in-browser key can send it · external = send from any wallet to the deposit address · none = quote only"
        },
        "origin": {
          "type": "boolean",
          "description": "Can be swapped FROM (live)"
        },
        "destination": {
          "type": "boolean",
          "description": "Can be swapped TO"
        }
      },
      "required": [
        "alias",
        "chain",
        "symbol",
        "assetId",
        "decimals",
        "contract",
        "signer",
        "origin",
        "destination"
      ]
    },
    "to": {
      "description": "Resolved destination",
      "type": "object",
      "properties": {
        "alias": {
          "type": "string",
          "description": "Canonical alias, e.g. USDC@base"
        },
        "chain": {
          "type": "string",
          "description": "ethereum | base | arbitrum | solana | sui | bitcoin | hyperliquid"
        },
        "symbol": {
          "type": "string",
          "description": "Ticker"
        },
        "assetId": {
          "type": "string",
          "description": "1Click asset id this alias resolves to"
        },
        "decimals": {
          "type": "number",
          "description": "Base-unit decimals"
        },
        "contract": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "EVM contract or Sui coin type; null for a native coin"
        },
        "signer": {
          "type": "string",
          "description": "browser = ONE's in-browser key can send it · external = send from any wallet to the deposit address · none = quote only"
        },
        "origin": {
          "type": "boolean",
          "description": "Can be swapped FROM (live)"
        },
        "destination": {
          "type": "boolean",
          "description": "Can be swapped TO"
        }
      },
      "required": [
        "alias",
        "chain",
        "symbol",
        "assetId",
        "decimals",
        "contract",
        "signer",
        "origin",
        "destination"
      ]
    },
    "route": {
      "description": "How the coins get there",
      "type": "object",
      "properties": {
        "via": {
          "type": "string",
          "description": "'1click' (NEAR Intents 1Click) — v1's only route"
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Human steps, in order"
        },
        "credits": {
          "description": "Hyperliquid only: 'perps' — USDC lands in the perps balance",
          "type": "string"
        }
      },
      "required": [
        "via",
        "steps"
      ]
    },
    "depositAddress": {
      "description": "Live only: the key swap:get takes. Send exactly send.amount here — verify it with 1Click first",
      "type": "string"
    },
    "amountIn": {
      "description": "Decimal you send",
      "type": "string"
    },
    "minAmountIn": {
      "description": "exact 'out': lowest input accepted, decimal",
      "type": "string"
    },
    "amountOut": {
      "description": "Decimal you receive (withdraw fee already taken)",
      "type": "string"
    },
    "minAmountOut": {
      "description": "Decimal floor after slippage",
      "type": "string"
    },
    "amountInUsd": {
      "description": "USD value in, per 1Click",
      "type": "string"
    },
    "amountOutUsd": {
      "description": "USD value out, per 1Click",
      "type": "string"
    },
    "costUsd": {
      "description": "amountInUsd − amountOutUsd, plus a possible Hyperliquid activation when it applies",
      "type": "string"
    },
    "fees": {
      "description": "Every fee read from the live quote — none hardcoded",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "description": "protocol (1Click) · app (ONE) · withdraw (destination chain) · refund (only on a refund)"
          },
          "bps": {
            "description": "Basis points, for protocol/app",
            "type": "number"
          },
          "amount": {
            "description": "Decimal amount",
            "type": "string"
          },
          "asset": {
            "description": "Alias the amount counts in",
            "type": "string"
          },
          "note": {
            "description": "One line for a human",
            "type": "string"
          }
        },
        "required": [
          "kind"
        ]
      }
    },
    "timeEstimateSec": {
      "description": "Seconds after the deposit confirms",
      "type": "number"
    },
    "refundAfter": {
      "description": "ISO: if not filled by now, refunds begin. Never send after this",
      "type": "string"
    },
    "addressExpires": {
      "description": "Live only, ISO: deposit address goes inactive",
      "type": "string"
    },
    "quotedAt": {
      "description": "1Click's timestamp — clients correct their clock skew with it before the deadline check",
      "type": "string"
    },
    "recipient": {
      "description": "Where the coins go — echoed",
      "type": "string"
    },
    "refundTo": {
      "description": "Where a refund goes — always your own address on the source chain",
      "type": "string"
    },
    "ownership": {
      "description": "Whose addresses these are, and how ONE knows",
      "type": "object",
      "properties": {
        "recipient": {
          "type": "string",
          "description": "proven (signature) · registered (your row, session only) · other (toOther) · placeholder (dry)"
        },
        "refundTo": {
          "type": "string",
          "description": "proven · registered · placeholder"
        },
        "note": {
          "type": "string",
          "description": "Which row each address came from and what was and was not verified, in one sentence"
        }
      },
      "required": [
        "recipient",
        "refundTo",
        "note"
      ]
    },
    "send": {
      "description": "Live only: the exact send instruction — plain transfer, self-custody wallet, no bridge",
      "type": "object",
      "properties": {
        "how": {
          "type": "string",
          "description": "browser · external"
        },
        "to": {
          "type": "string",
          "description": "The deposit address"
        },
        "amountBase": {
          "type": "string",
          "description": "Exact base units"
        },
        "amount": {
          "type": "string",
          "description": "Same, as a decimal"
        },
        "asset": {
          "type": "string",
          "description": "Alias to send"
        },
        "chain": {
          "type": "string",
          "description": "Chain to send on — the wrong chain loses funds"
        },
        "uri": {
          "description": "Wallet link: bitcoin: (BIP21), solana:, or ethereum: (EIP-681); scan or tap in any wallet",
          "type": "string"
        },
        "refundsTo": {
          "type": "string",
          "description": "Where a failed swap refunds, and how to recover it, in one sentence"
        }
      },
      "required": [
        "how",
        "to",
        "amountBase",
        "amount",
        "asset",
        "chain",
        "refundsTo"
      ]
    },
    "hyperliquid": {
      "description": "Hyperliquid destination with YOUR recipient only — absent for placeholders",
      "type": "object",
      "properties": {
        "checked": {
          "type": "boolean",
          "description": "false = the account read failed; treated as possibly new"
        },
        "firstDeposit": {
          "type": "boolean",
          "description": "true = empty account; Hyperliquid MAY take a one-time ~1 USDC activation (unverified)"
        }
      },
      "required": [
        "checked",
        "firstDeposit"
      ]
    },
    "keyed": {
      "description": "true = ONE's partner key was used (live only); false = keyless fee schedule",
      "type": "boolean"
    },
    "warnings": {
      "description": "poor_rate:<pct kept> · possible_activation_fee · external_send · jwt_rejected · app_fee_off · amount_too_small_for_fees (dry only; live refuses) · exact_out_needs_funded_account (dry only; live refuses)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "link": {
      "description": "Absolute one.ie URL: dry = a prefilled /swap form a person can sign from · live = its status page",
      "type": "string"
    },
    "next": {
      "type": "string",
      "description": "One sentence: what to do now. An agent cannot sign — give the person the link, or the exact send line"
    }
  },
  "required": [
    "ok",
    "network",
    "next"
  ]
}