> For the complete documentation index, see [llms.txt](https://docs.peach.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peach.ag/api-reference/arc-aggregator/swap.md).

# Swap

Get quote amounts and transaction data in one request. See the direct HTTP integration example below.

## Build swap calldata

> Returns a fresh quote and signed swap calldata for Direct Allowance. The payer must be the executor; this endpoint does not broadcast the transaction.

```json
{"openapi":"3.0.3","info":{"title":"Arc Aggregator HTTP API","version":"1.0.0"},"tags":[{"name":"Swap"}],"servers":[{"url":"https://api.peach.ag/arc","description":"Arc Mainnet (chain ID 5042)"}],"paths":{"/router/swap":{"get":{"operationId":"arcSwap","tags":["Swap"],"summary":"Build swap calldata","description":"Returns a fresh quote and signed swap calldata for Direct Allowance. The payer must be the executor; this endpoint does not broadcast the transaction.","parameters":[{"$ref":"#/components/parameters/From"},{"$ref":"#/components/parameters/Target"},{"$ref":"#/components/parameters/Amount"},{"$ref":"#/components/parameters/Executor"},{"name":"payer","in":"query","description":"Input token owner. Defaults to executor and must equal executor.","schema":{"$ref":"#/components/schemas/Address"}},{"name":"recipient","in":"query","description":"Output receiver. Defaults to executor; must be non-zero and different from the Execution Router.","schema":{"$ref":"#/components/schemas/Address"}},{"$ref":"#/components/parameters/ByAmountIn"},{"$ref":"#/components/parameters/Version"},{"$ref":"#/components/parameters/Depth"},{"$ref":"#/components/parameters/SplitCount"},{"$ref":"#/components/parameters/Providers"},{"$ref":"#/components/parameters/Slippage"},{"$ref":"#/components/parameters/Deadline"},{"$ref":"#/components/parameters/CustomFeeBps"},{"$ref":"#/components/parameters/CustomFeeReceiver"},{"$ref":"#/components/parameters/Gas"},{"$ref":"#/components/parameters/CalPathLimit"},{"$ref":"#/components/parameters/NativeIn"},{"$ref":"#/components/parameters/NativeOut"}],"responses":{"200":{"description":"Signed swap plan and transaction calldata.","headers":{"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SwapData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServiceInternalError"},"503":{"$ref":"#/components/responses/ServiceCircuitBreaking"}}}}},"components":{"parameters":{"From":{"name":"from","in":"query","required":true,"description":"Input ERC-20 address. For USDC use its ERC-20 interface, 0x3600000000000000000000000000000000000000; native-token sentinels are unsupported.","schema":{"$ref":"#/components/schemas/Address"}},"Target":{"name":"target","in":"query","required":true,"description":"Output ERC-20 address; must differ from from.","schema":{"$ref":"#/components/schemas/Address"}},"Amount":{"name":"amount","in":"query","required":true,"description":"Positive base-unit integer string, at most 340282366920938463463374607431768211455 (u128).","schema":{"type":"string","pattern":"^[0-9]+$"}},"Executor":{"name":"executor","in":"query","required":true,"description":"Final transaction sender. HTTP also accepts sender as an alias; send one name only. Must be non-zero and different from the Execution Router.","schema":{"$ref":"#/components/schemas/Address"}},"ByAmountIn":{"name":"by_amount_in","in":"query","description":"If true, amount is the input; if false, amount is the desired quote output. Execution still uses a fixed input with a minimum output, not an exact-output guarantee. Custom fees require true.","schema":{"type":"boolean","default":true}},"Version":{"name":"v","in":"query","description":"Client version identifier; send 1001500, matching route-preview requests.","schema":{"type":"integer","minimum":0}},"Depth":{"name":"depth","in":"query","description":"Route depth, subject to deployment limits. Omitted or zero uses server configuration.","schema":{"type":"integer","minimum":0}},"SplitCount":{"name":"split_count","in":"query","description":"Requested split count, adjusted by server limits and trade size. Does not equal final execution-step count.","schema":{"type":"integer","minimum":0}},"Providers":{"name":"providers","in":"query","description":"Comma-separated provider IDs from /router/status. Omit for server selection; availability varies by network.","schema":{"type":"string"}},"Slippage":{"name":"slippage_bps","in":"query","description":"Basis points applied to net expect_amount_out after custom fees. Minimum output is floor(expect_amount_out * (10000 - slippage_bps) / 10000). Omitted uses the server default; send explicitly.","schema":{"type":"integer","minimum":0,"maximum":9999}},"Deadline":{"name":"deadline_secs","in":"query","description":"Validity in seconds from construction, not an absolute timestamp. Send a positive value; omitted uses the server default. Delegated plans also enforce the server lifetime cap.","schema":{"type":"integer","minimum":1}},"CustomFeeBps":{"name":"custom_fee_bps","in":"query","description":"Output-token custom fee in basis points, subject to /router/status arc_router.max_custom_fee_bps and on-chain policy. Positive values require by_amount_in=true and custom_fee_receiver.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},"CustomFeeReceiver":{"name":"custom_fee_receiver","in":"query","description":"Required for a positive custom fee; non-zero and different from recipient and the Execution Router.","schema":{"$ref":"#/components/schemas/Address"}},"Gas":{"name":"gas","in":"query","description":"Advanced gas-unit override. Omit for the server's buffered execution estimate; this is not a gas price or a transaction simulation.","schema":{"type":"integer","minimum":0}},"CalPathLimit":{"name":"cal_path_limit","in":"query","description":"Advanced route-search bound. Omit to use server configuration.","schema":{"type":"integer","minimum":0}},"NativeIn":{"name":"native_in","in":"query","description":"Arc supports ERC-20 input only. Omit or send false; true is rejected.","schema":{"type":"boolean","enum":[false],"default":false}},"NativeOut":{"name":"native_out","in":"query","description":"Arc supports ERC-20 output only. Omit or send false; true is rejected.","schema":{"type":"boolean","enum":[false],"default":false}}},"schemas":{"Address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"ApiResponse":{"type":"object","required":["code","msg"],"description":"Check JSON `code` even on HTTP 200. `200` means success; errors omit `data`. See [Error Codes](https://docs.peach.ag/api-reference/arc-aggregator/error-codes).","properties":{"code":{"type":"integer"},"msg":{"type":"string"}}},"SwapData":{"type":"object","required":["request_id","quote_id","quote_ts","amount_in","amount_out","expect_amount_out","custom_fee_bps","custom_fee_amount","integrator_fee_amount","protocol_fee_amount","custom_fee_receiver","protocol_cut_bps","deviation_ratio","contracts","gas","execution_mode","execution_status","plan_hash","aggregator_signature","aggregator_signer","payer","executor","recipient","tx"],"properties":{"request_id":{"type":"string","description":"Identifier for this final quote request."},"quote_id":{"$ref":"#/components/schemas/Bytes32"},"quote_ts":{"type":"integer","description":"Final quote timestamp in Unix milliseconds."},"amount_in":{"allOf":[{"$ref":"#/components/schemas/Amount"}],"description":"Input amount taken from payer, including any modeled input transfer tax."},"amount_out":{"allOf":[{"$ref":"#/components/schemas/Amount"}],"description":"Quoted route output before aggregator custom fees."},"expect_amount_out":{"allOf":[{"$ref":"#/components/schemas/Amount"}],"description":"Expected recipient output after custom fees."},"custom_fee_bps":{"type":"integer","description":"Total output custom fee rate in basis points."},"custom_fee_amount":{"$ref":"#/components/schemas/Amount"},"integrator_fee_amount":{"$ref":"#/components/schemas/Amount"},"protocol_fee_amount":{"$ref":"#/components/schemas/Amount"},"custom_fee_receiver":{"type":"string","description":"Integrator fee recipient address, or an empty string when no custom fee applies."},"protocol_cut_bps":{"type":"integer","description":"Protocol share of the custom fee; not another rate on the entire output. Zero without a custom fee."},"deviation_ratio":{"type":"string","description":"Price-deviation metadata; may be empty when the check is skipped."},"deviation_skip_reason":{"type":"string","description":"Present when the price-deviation check is skipped."},"contracts":{"type":"object","required":["execution_router"],"properties":{"execution_router":{"$ref":"#/components/schemas/Address"}}},"gas":{"type":"integer","description":"Execution gas units; estimate with buffer unless explicitly overridden. Not a simulation guarantee."},"execution_mode":{"type":"string","enum":["DIRECT_ALLOWANCE"]},"execution_status":{"type":"string","enum":["TRANSACTION_READY"]},"plan_hash":{"$ref":"#/components/schemas/Bytes32"},"aggregator_signature":{"type":"string","description":"Hex-encoded aggregator EIP-712 plan signature, already encoded into tx.data."},"aggregator_signer":{"$ref":"#/components/schemas/Address"},"payer":{"$ref":"#/components/schemas/Address"},"executor":{"$ref":"#/components/schemas/Address"},"recipient":{"$ref":"#/components/schemas/Address"},"tx":{"$ref":"#/components/schemas/Transaction"}}},"Bytes32":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"Amount":{"type":"string","pattern":"^[0-9]+$","description":"Decimal integer string in token base units."},"Transaction":{"type":"object","required":["to","data","value","entrypoint","amount_out_min"],"properties":{"to":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Execution Router on the selected chain; matches contracts.execution_router for Direct swaps."},"data":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Complete executePlan calldata including the signed plan and route. Submit unchanged after validation."},"value":{"type":"string","enum":["0"],"description":"Native transaction value; always zero for Arc ERC-20 swaps."},"entrypoint":{"type":"string","enum":["executePlan"]},"amount_out_min":{"allOf":[{"$ref":"#/components/schemas/Amount"}],"description":"Minimum net output to recipient, after custom fee and slippage."}}}},"responses":{"BadRequest":{"description":"Request parsing failed: malformed/missing query parameters or invalid JSON syntax. The body may be plain text; this is HTTP 400, not application code 400.","content":{"text/plain":{"schema":{"type":"string"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Retry with backoff and honor Retry-After when present."},"ServiceInternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"ServiceCircuitBreaking":{"description":"Service rate limit exceeded. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}}
```

Call `GET https://api.peach.ag/arc/router/swap` once with the order and executor. The response includes quote amounts and `tx`; no separate quote call is needed. Direct swaps require `payer = executor`. For a different payer, use **prepare → payer signature → build**.

Use ERC-20 token addresses. Arc USDC uses its 6-decimal ERC-20 interface, `0x3600000000000000000000000000000000000000`; native-token sentinels and native input/output are unsupported.

### Call the API directly

Use values from the user's order and connected wallet. `amount` is a positive decimal integer in input-token base units. This example makes one Aggregator request and does not broadcast.

```javascript
async function requestSwap({ from, target, amount, executor }) {
  const query = new URLSearchParams({
    from, target, amount: amount.toString(), executor,
    by_amount_in: 'true', v: '1001500',
    slippage_bps: '50', deadline_secs: '120',
  });
  const response = await fetch(`https://api.peach.ag/arc/router/swap?${query}`, { cache: 'no-store' });
  const body = await response.json(); // Non-JSON failures reject here.
  if (!response.ok || body.code !== 200 || !body.data) {
    throw new Error(body.msg ?? `Swap request failed: ${response.status}`);
  }
  const result = body.data;
  if (result.execution_mode !== 'DIRECT_ALLOWANCE' ||
      result.execution_status !== 'TRANSACTION_READY' || !result.tx) {
    throw new Error('Expected a ready Direct swap');
  }
  return result; // Retain this complete result for review and submission.
}
```

For authenticated integrations, add your `apikey` using the integration's credential handling.

### Review and submit the same result

Display `result.expect_amount_out`, `result.tx.amount_out_min`, recipient and fees, then wait for the user's confirmation. Before approval or sending, decode and validate the signed execution plan/calldata against your intended chain 5042, trusted router, tokens, amount, payer/executor/recipient, minimum, fees and deadline. Checking the JSON envelope alone does not perform these validations.

For ERC-20 input, approve the validated Execution Router when allowance is insufficient and wait for the approval receipt. Recheck the wallet account, network and signed expiry, then simulate the exact returned transaction.

After those checks and user confirmation, submit `{ from: executor, to: result.tx.to, data: result.tx.data, value }` using the wallet's transaction API. With `eth_sendTransaction`, encode value as `'0x' + BigInt(result.tx.value).toString(16)`. Preserve the returned transaction target, calldata and numeric value; gas/nonce are wallet or RPC concerns. Save the transaction hash before waiting for the receipt, and verify receipt success.

Do not request swap again when the user confirms. If the result expires, the order changes, or you refresh the quote, obtain and confirm a new complete result. A wallet timeout is not proof that sending failed; inspect the hash/wallet before retrying.

### HTTP endpoint reference

The schema and cURL example above describe the same single request. Historical sample responses are illustrative; never submit their expired calldata.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peach.ag/api-reference/arc-aggregator/swap.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
