Skip to main content
Glama

arcgate

by dev.arcgate
OverviewDiscussionsAdmin

tradeSwap

Turns a stored quote into unsigned transactions for the taker to sign and send. arcgate never signs, broadcasts or holds funds.

  • Cost: 0.01 USDC to 5 USDC per call by the quote's USD size, paid over x402. A quote with no USD value, or an unknown or expired one, costs the first tier. It is charged once per quote: tradeSwapTx is free.

    • under $1,000: 0.01 USDC.

    • $1,000 to $10,000: 0.05 USDC.

    • above $10,000 up to $100,000: 0.50 USDC.

    • above $100,000: 5 USDC.

  • Inputs: quoteId and taker, and optional recipient, deadlineSec and approval. Never permit: it belongs to tradeSwapTx, and sending it here is 400 invalid_request.

  • Returns: unsigned transactions to send in order, signatures when a Permit2 signature is needed, warnings and next. Read what you sign. approval: "permit2" can send an unlimited approve of Permit2 that stays after the trade. When every source pool of the route trades native USDC, the swap pays by value: no approval, no signature.

  • Errors:

    • 404 quote_not_found: no such quote. Quote again.

    • 409 quote_stale or 410 quote_expired: the price moved below the stored minAmountOut, or the quote outlived its ttlSec. The answer carries a free fresh quote when it can be traded. Check its price, safety.verdict and readiness, then swap its quoteId.

    • 422 insufficient_balance: the taker lacks the input or the native USDC for gas and the fee. Tell the user.

    • 422 swap_reverts: the pre-flight simulation reverted. Stop.

    • 422 cannot_sell: the token cannot be sold, or its sell tax is at or above 9000 basis points (trade.quote.honeypot_sell_tax_bps). Stop.

    • 422 high_tax: the token can be sold, but its sell tax is above 1000 basis points (trade.quote.max_sell_tax_bps). Stop.

    • 422 sell_unverified: the quote's sell check could not confirm the token can be sold, or the re-check from the recipient wallet could not. Stop.

    • 422 exit_risk_high: the quote was asked with exitRisk stop and the token it buys rated high. The quote's own policy and level decide; nothing is read again. Stop.

    • 422 not_executable: no executable route is left. Stop.

    • 429 swap_attempts_exhausted: this quote has used its 5 failed calls. Every error counts except quote_not_found and invalid_request. So does a payment that fails to settle and an answer that is not delivered. Quote again.

  • Next:

    • tradeSwapTx: when next is sign_permit, send the signed permit (free).

    • tradeReceipt: when next is send, confirm the fill once you have sent the transactions.

Costs 0.01 USDC under $1,000; 0.05 USDC from $1,000 to $10,000; 0.50 USDC above $10,000 up to $100,000; 5 USDC above $100,000; the exact amount for your quoteId comes back in the payment-required result. Payment goes in params._meta["x402/payment"]; use an x402-aware MCP client (see https://docs.arcgate.dev/#arcgate/description/mcp-for-agents).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
takerYesThe wallet that signs and sends the transactions. It holds the input token.
quoteIdYesThe quoteId from tradeQuote. A quote lives for its `ttlSec`, at most 120 seconds.
approvalNo`permit2` (default): an unlimited ERC-20 approve of Permit2 when the allowance is short, which stays after the trade, then a Permit2 signature to sign and send to tradeSwapTx. `approve`: at most one exact-amount ERC-20 approve of ArcgateRouter, and no signature.permit2
recipientNoThe address that receives the output. Defaults to `taker`.
deadlineSecNoSeconds from now until the swap transaction expires on chain, 10-600 (default 60).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / approval / description
      Added value: +"`permit2` (default): an unlimited ERC-20 approve of Permit2 when the allowance is short, which stays after the trade, then a Permit2 signature to sign and send to tradeSwapTx. `approve`: at most one exact-amount ERC-20 approve of ArcgateRouter, and no signature."
    • addedInput schema / properties / deadlineSec / description
      Added value: +"Seconds from now until the swap transaction expires on chain, 10-600 (default 60)."
    • addedInput schema / properties / quoteId / description
      Added value: +"The quoteId from tradeQuote. A quote lives for its `ttlSec`, at most 120 seconds."
    • addedInput schema / properties / recipient / description
      Added value: +"The address that receives the output. Defaults to `taker`."
    • addedInput schema / properties / taker / description
      Added value: +"The wallet that signs and sends the transactions. It holds the input token."
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: per-call x402 cost tiers, one-charge-per-quote rule, the persistence of an unlimited Permit2 approval, the native-USDC no-approval path, and a complete error taxonomy with charges and stop conditions. This is the kind of detail an agent cannot get from any structured field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded with bold section headers (Cost, Inputs, Returns, Errors, Next) and dense bullets. However, the cost tier table is restated almost verbatim in the closing paragraph, which is pure duplication and adds length without new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-output-schema, paid, multi-step swap tool, the description covers inputs, returns, cost, payment channel, all failure modes with their recovery actions, and the follow-up calls. Nothing an agent needs in order to invoke or recover from this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it enumerates which parameters are required vs optional and warns that `permit` is invalid here (400 invalid_request), steering the agent away from a plausible mistake. It does not add syntax beyond the schema, hence not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Turns a stored quote into unsigned transactions for the taker to sign and send', and immediately scopes arcgate's role ('never signs, broadcasts or holds funds'). This clearly separates it from tradeQuote (creates the quote), tradeSwapTx (signs the permit) and tradeReceipt (confirms the fill), all named in the description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: 'tradeSwapTx: when next is sign_permit' and 'tradeReceipt: when next is send', plus the precondition that a stored quote must exist. It also names an alternative tool for the permit step and says never to pass `permit` here, giving both when-to-use and when-not.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All arcgate toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources