Skip to main content
Glama

arcgate

by dev.arcgate
OverviewDiscussionsAdmin

tradeSwapTx

The free Permit2 second round: finishes a POST /trade/v1/swap call whose signatures asked the taker to sign a Permit2 PermitSingle.

  • Cost: free, never x402-gated - a payment header, if one is sent anyway, is ignored and nobody is charged. Only reachable once, right after the paid call that opened it.

  • Key inputs: the SAME quoteId, taker and recipient (defaults to taker) as the paid POST /trade/v1/swap call, plus deadlineSec and the required permit: { message: signatures[0].typedData.message, signature } (sign typedData with the taker's key, EIP-712, e.g. viem's signTypedData). permit accepts only message and signature, end to end - any other field, at any level, is 400 invalid_request at parse. The service rebuilds the Permit2 domain itself and checks the signer, spender, token, amount, nonce and both deadlines: a mismatched spender or token, or an amount below amountIn (a larger amount is accepted), is 400 invalid_request; a stale nonce, an expired sigDeadline/expiration, or an invalid signature (verified via ERC-1271 on chain for a contract taker) is 422 swap_reverts. A contract taker can swap, but POST /trade/v1/receipt only reads transactions the taker sends itself, so it answers invalid_request for a Safe, ERC-4337 or batching EIP-7702 wallet: check your own transaction receipt instead.

  • No pending round: 409 no_pending_swap when this quoteId/taker/recipient never paid, named a different taker or recipient, or already used its one free call - call POST /trade/v1/swap first, which is paid and returns the permit this call takes.

  • Freshness: re-quotes and re-simulates exactly like POST /trade/v1/swap, and can answer the SAME 410 quote_expired/409 quote_stale it would - but never with a fresh quote (issue #124's free re-quote is /trade/v1/swap's own paid-quote courtesy, not this free route's).

  • Attempts: a permit round (quoteId, taker, recipient) gets at most 5 failed calls; the next one is 429 swap_attempts_exhausted (next: "requote"), answered without running the swap pipeline. A failed call is a 400 from the permit checks above, a 409, 422, 500 or 503, or an undelivered 200; a delivered 200, a 400 at parse, a 404, a 410 or no_pending_swap uses none. Failed POST /trade/v1/swap calls don't count here. A new POST /trade/v1/swap permit response resets this round's attempts only once delivered (after settlement when paid).

  • Next: sign and send transactions in order, then confirm the fill with POST /trade/v1/receipt (free). This is the last call in search -> quote -> swap -> swap/tx.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
takerYes
permitYes
quoteIdYes
recipientNo
deadlineSecNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/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 delivers: cost model (free, x402 header ignored), single-use reachability, the 409/422/429 error taxonomy with retry accounting (5 failed attempts, next: requote), signature-validation rules (ERC-1271, nonce/deadline checks), and the receipt caveat for Safe/4337/7702 takers. This is well beyond what any structured field provides.

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?

Front-loaded with purpose then bolded bullet headers make it scannable, and virtually every sentence carries operational content. It is dense and long, with some restatement (free/x402 repeated across cost and freshness notes), so not a perfect 5, but nothing is filler.

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 5-param nested-Object tool with 0% schema descriptions and no output schema, the description covers inputs, error semantics, attempt limits, freshness behavior and the downstream confirmation step. An agent has everything needed to invoke it correctly and interpret failures.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate and does: it maps quoteId/taker/recipient to the paid call, gives recipient's default, names deadlineSec, and spells out the permit object shape (only message+signature allowed end-to-end, extra fields 400) plus which fields are validated and how. No parameter is left to guesswork.

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?

Opens with a specific verb+resource+scope: it is the free Permit2 second round that finishes a POST /trade/v1/swap call whose signatures requested a PermitSingle. This cleanly distinguishes it from the sibling tradeSwap (the paid first round) without needing to open either schema.

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?

States the exact precondition ('only reachable once, right after the paid call that opened it'), names the alternative to call when no pending round exists (POST /trade/v1/swap), and closes by placing it in the pipeline 'search -> quote -> swap -> swap/tx'. When/when-not/alternatives are all explicit.

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