> ## Documentation Index
> Fetch the complete documentation index at: https://digraphsas-docs-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Market swap price and calldata

> Price and calldata in one call: GET /prices and POST /transactions fused into a single Market request.

`GET /swap` fuses the two Market steps into one request: it runs aggregator [pricing](/api-reference/market/prices) and [calldata generation](/api-reference/market/transactions) server-side and hands back both the `priceRoute` and ready-to-broadcast `txParams`. One round-trip takes you from "what's the rate?" to a transaction you can sign and send.

<Note>
  Prefer the two-step flow ([`GET /prices`](/api-reference/market/prices) → [`POST /transactions/:chainId`](/api-reference/market/transactions)) when you need to inspect or cache the route before committing, manage allowances yourself, or attach `permit` / `permit2` data. `/swap` trades that control for a single call.
</Note>

## When to use it

| Reach for `/swap` when…                             | Use the two-step flow when…                                   |
| --------------------------------------------------- | ------------------------------------------------------------- |
| You want the fastest path from quote to signable tx | You need to inspect, display, or cache the `priceRoute` first |
| One server round-trip matters (latency, simplicity) | You attach `permit` / `permit2` to skip the approve tx        |
| Server-built calldata with defaults is fine         | You need RFQ liquidity or finer routing/fee control           |

## Response

A `200` returns two objects:

* **`priceRoute`** — the routing plan: `bestRoute`, `srcAmount` / `destAmount`, `gasCost` / `gasCostUSD`, `srcUSD` / `destUSD`, `contractMethod`, `version`, and an `hmac` integrity tag. Same shape as [`GET /prices`](/api-reference/market/prices).
* **`txParams`** — a broadcastable tx envelope: `from`, `to` (the Augustus v6.2 router), `value`, `data` (encoded swap), `gasPrice`, and `chainId`. **No `gas` field** — estimate it locally.

```json theme={null}
{
  "priceRoute": {
    "blockNumber": 20184108,
    "network": 1,
    "srcToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "srcDecimals": 6,
    "srcAmount": "1000000",
    "destToken": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "destDecimals": 18,
    "destAmount": "997620341641628401",
    "bestRoute": ["…"],
    "gasCostUSD": "5.932529",
    "contractMethod": "swapExactAmountIn",
    "version": "6.2",
    "hmac": "…"
  },
  "txParams": {
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0x6a000f20005980200259b80c5102003040001068",
    "value": "0",
    "data": "0xe3ead59e…",
    "gasPrice": "16000000000",
    "chainId": 1
  }
}
```

## Broadcasting the transaction

`txParams` is ready to send, but `/swap` skips allowance and balance checks and returns no `gas` field. Before broadcasting:

<Steps>
  <Step title="Approve (ERC-20 source only)">
    Approve the Augustus v6.2 router (`txParams.to`) to spend `srcToken` with a standard `approve(to, amount)`. Native sources (ETH, etc.) skip this; the amount rides along in `txParams.value`. To drop the extra transaction, switch to the two-step flow and pass Permit / Permit2 data in the build call.
  </Step>

  <Step title="Estimate gas">
    Run `eth_estimateGas` on `txParams` (or simulate the call). The response omits `gas` by design; never broadcast with a hardcoded limit.
  </Step>

  <Step title="Sign & send">
    Sign `txParams` with the user's wallet and broadcast. Settlement is atomic: the swap completes or reverts, and it reverts if the delivered amount falls below the slippage-adjusted minimum.
  </Step>
</Steps>

## Limitations

<Warning>
  `/swap` runs at lower rate limits than the individual endpoints ([Pro API accounts](/overview/pro-api-accounts) lift them) and excludes RFQ liquidity (AugustusRFQ). For best price across every venue, or to inspect the route before building, use [`GET /prices`](/api-reference/market/prices).
</Warning>

* The endpoint validates neither allowance nor balance; your client must ensure the user has approved and funded the swap.
* The response carries no `gas` field. Always estimate locally before broadcasting.
* Swap & Transfer and fees don't apply to the `swapOnUniswap*` / `swapOnZeroXv*` contract methods. When you set a `receiver` or a partner fee, constrain routing with `includeContractMethods=simpleSwap,multiSwap,megaSwap`.
* For tax tokens, DEXs and methods that can't handle transfer-fee tokens are filtered out; declare the fee via `srcTokenTransferFee` / `destTokenTransferFee`.

## Key parameters

* **`userAddress`** (required) — the caller, used as the tx `from` and for fee/surplus accounting. When using an intermediary contract, `userAddress` should correspond to `msg.sender` and `receiver` to the recipient.
* **`slippage`** — basis points: `100` = 1%, `250` = 2.5%, max `10000`.
* **`version`** — always pass `6.2` (Augustus v6.2); when omitted the API falls back to the legacy v5 router.
* **`partner` / `partnerFeeBps` / `partnerAddress`** — monetize the swap; `isSurplusToUser` and `isDirectFeeTransfer` control surplus and fee routing. See [Monetization](/overview/monetization).

## Related pages

<CardGroup cols={2}>
  <Card title="GET /prices" icon="magnifying-glass-dollar" href="/api-reference/market/prices">
    Pricing only: inspect or cache the route before building.
  </Card>

  <Card title="POST /transactions/:chainId" icon="file-signature" href="/api-reference/market/transactions">
    Build calldata from a priceRoute you already hold.
  </Card>

  <Card title="How Market works" icon="route" href="/market/how-it-works">
    Price → build → approve → settle, end to end.
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/api-reference/troubleshooting">
    Market failure modes: symptom, cause, fix.
  </Card>
</CardGroup>


## OpenAPI

````yaml api-reference/specs/market.json GET /swap
openapi: 3.0.3
info:
  title: Velora Market API
  version: 1.0.0
  description: Velora Market API — direct aggregator pricing and Augustus calldata.
servers:
  - url: https://api.velora.xyz
    description: Production
security: []
externalDocs:
  description: Market — how it works (prices → calldata → broadcast).
  url: https://velora.xyz/docs/market/how-it-works
paths:
  /swap:
    get:
      summary: Get a Market route and ready-to-broadcast tx in one call
      description: >-
        Combines GET /prices and POST /transactions into a single request:
        returns the optimal `priceRoute` plus ready-to-broadcast `txParams`.
        Convenient for streamlined execution. Trade-offs vs the two-step flow:
        lower rate limits, RFQ liquidity is excluded, allowances and balances
        are not checked, and `txParams` carries no `gas` field — estimate gas
        locally before broadcasting.
      operationId: marketSwap
      parameters:
        - name: srcToken
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Address'
          example: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
          description: >-
            Source token address. A token symbol listed in /tokens can be used
            instead. Example uses ETH.
        - name: srcDecimals
          in: query
          required: false
          schema:
            type: integer
          example: 18
          description: >-
            Source token decimals. Can be omitted if a token symbol is used in
            srcToken.
        - name: destToken
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Address'
          example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
          description: >-
            Destination token address. A token symbol listed in /tokens can be
            used instead. Example uses USDC.
        - name: destDecimals
          in: query
          required: false
          schema:
            type: integer
          example: 6
          description: >-
            Destination token decimals. Can be omitted if a token symbol is used
            in destToken.
        - name: amount
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/TokenAmount'
          example: '1000000000000000000'
          description: srcToken amount (SELL) or destToken amount (BUY), in WEI/raw units.
        - name: side
          in: query
          required: false
          schema:
            type: string
            enum:
              - SELL
              - BUY
            default: SELL
        - name: network
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ChainId'
          example: 1
          description: >-
            EVM chain ID. Default: 1 (Mainnet). Market uses `network`; Delta
            uses `chainId`.
        - name: slippage
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 10000
          example: 100
          description: Allowed slippage in basis points (0–10000). `100` = 1%.
        - name: userAddress
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Address'
          example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
          description: >-
            Caller wallet address. Used as the transaction `from`. When using an
            intermediary contract, userAddress should correspond to msg.sender
            and receiver to the recipient.
        - name: receiver
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Address'
          description: >-
            Output recipient for Swap & Transfer. Omit when swapping from/to the
            same account.
        - name: partner
          in: query
          required: false
          schema:
            type: string
            default: anon
          example: my-app-name
          description: >-
            Partner string. Defaults to `anon` which charges 1bps fee for all
            swaps.
        - name: partnerAddress
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Address'
          description: Partner fee / surplus recipient address.
        - name: partnerFeeBps
          in: query
          required: false
          schema:
            type: string
          description: Partner fee in basis points.
        - name: otherExchangePrices
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            If true, the response includes competitor price quotes in an
            `others` object.
        - name: includeDEXS
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of DEXs to include.
        - name: excludeDEXS
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of DEXs to exclude.
        - name: includeContractMethods
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of contract methods to include.
        - name: excludeContractMethods
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of contract methods to exclude.
        - name: maxImpact
          in: query
          required: false
          schema:
            type: number
          description: Bypass API price-impact check (default = 15%). Value in %.
        - name: route
          in: query
          required: false
          schema:
            type: string
          description: Dash-separated list of tokens for the price route. Max 4 tokens.
        - name: srcTokenTransferFee
          in: query
          required: false
          schema:
            type: string
          description: Tax in basis points charged on srcToken transfers.
        - name: destTokenTransferFee
          in: query
          required: false
          schema:
            type: string
          description: Tax in basis points charged on destToken transfers.
        - name: srcTokenDexTransferFee
          in: query
          required: false
          schema:
            type: string
          description: DEX-specific tax in basis points charged on srcToken transfers.
        - name: destTokenDexTransferFee
          in: query
          required: false
          schema:
            type: string
          description: DEX-specific tax in basis points charged on destToken transfers.
        - name: version
          in: query
          required: false
          schema:
            type: string
            enum:
              - '5'
              - '6.2'
            default: '5'
          example: '6.2'
          description: >-
            Protocol version. Always pass `6.2` (Augustus v6.2, what these docs
            cover); when omitted the API falls back to the legacy v5 router.
        - name: ignoreBadUsdPrice
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Skip the USD-price availability check.
        - name: takeSurplus
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Collect positive slippage as surplus. Works with partnerAddress.
        - name: isCapSurplus
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Cap collected surplus at 1%.
        - name: isSurplusToUser
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            Route positive slippage / surplus to the user instead of the
            partner.
        - name: isDirectFeeTransfer
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            Transfer the partner fee directly rather than accruing it in the Fee
            Vault.
      responses:
        '200':
          description: >-
            Optimal route plus ready-to-broadcast tx params. Calldata targets
            Augustus v6.2 when `version=6.2`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketSwapResponse'
        '400':
          description: >-
            Invalid request. Documented examples: `InvalidInput`,
            `PricingError`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unsupported chain or token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Address:
      type: string
      description: >-
        EVM address (20 bytes, hex-encoded with `0x` prefix). Use the mixed-case
        placeholder `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native ETH.
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
    TokenAmount:
      type: string
      description: >-
        Token amount in WEI / raw units (no decimal point). Serialized as a
        string to preserve precision for amounts that exceed JavaScript Number
        range.
      example: '1000000000000000000'
    ChainId:
      type: integer
      description: >-
        EVM chain ID. Supported values today include 1 (Mainnet), 10 (Optimism),
        56 (BSC), 137 (Polygon), 8453 (Base), 42161 (Arbitrum), 43114
        (Avalanche), 100 (Gnosis). The set is open — call GET /chains for the
        live list.
      example: 1
    MarketSwapResponse:
      type: object
      description: >-
        GET /swap envelope — pricing (`priceRoute`) plus a ready-to-broadcast tx
        (`txParams`) in one call.
      properties:
        priceRoute:
          $ref: '#/components/schemas/MarketPriceRoute'
        txParams:
          $ref: '#/components/schemas/MarketTransactionResponse'
    ErrorResponse:
      type: object
      description: Standard Velora error envelope.
      required:
        - errorType
      properties:
        errorType:
          $ref: '#/components/schemas/ErrorCode'
        details:
          type: string
          description: Human-readable description of the failure.
      example:
        errorType: PricingError
        details: Error getting price data
    MarketPriceRoute:
      type: object
      description: >-
        Market route block. Calldata-ready against Augustus v6.2 when
        `version=6.2`.
      properties:
        blockNumber:
          type: integer
        network:
          $ref: '#/components/schemas/ChainId'
        srcToken:
          $ref: '#/components/schemas/Address'
        srcDecimals:
          type: integer
        srcAmount:
          $ref: '#/components/schemas/TokenAmount'
        destToken:
          $ref: '#/components/schemas/Address'
        destDecimals:
          type: integer
        destAmount:
          $ref: '#/components/schemas/TokenAmount'
        bestRoute:
          type: array
          items:
            type: object
        gasCostUSD:
          type: string
        gasCost:
          type: string
        side:
          type: string
          enum:
            - SELL
            - BUY
        version:
          type: string
        contractAddress:
          $ref: '#/components/schemas/Address'
        tokenTransferProxy:
          $ref: '#/components/schemas/Address'
        contractMethod:
          type: string
        partnerFee:
          type: number
        srcUSD:
          type: string
        destUSD:
          type: string
        partner:
          type: string
        maxImpactReached:
          type: boolean
        hmac:
          type: string
    MarketTransactionResponse:
      type: object
      description: Augustus calldata + tx envelope ready to broadcast.
      properties:
        from:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: End-user wallet address (the `userAddress` from the request).
        to:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: >-
            The Augustus v6.2 router. Send the transaction here; it is also the
            ERC-20 spender to approve.
        value:
          type: string
          example: '0'
          description: >-
            Native token amount in WEI to send with the transaction. `"0"` for
            ERC-20 sources.
        data:
          type: string
          description: Encoded swap calldata.
        gasPrice:
          type: string
          example: '16000000000'
          description: >-
            Suggested gas price in WEI. Replaced by maxFeePerGas /
            maxPriorityFeePerGas when `eip1559=true`.
        maxFeePerGas:
          type: string
          description: EIP-1559 max fee per gas in WEI. Present when `eip1559=true`.
        maxPriorityFeePerGas:
          type: string
          description: >-
            EIP-1559 max priority fee per gas in WEI. Present when
            `eip1559=true`.
        gas:
          type: string
          description: >-
            Gas limit estimate from the API's transaction checks. Returned by
            POST /transactions unless `ignoreChecks` or `ignoreGasEstimate` is
            set; omitted by GET /swap, where you estimate locally before
            broadcasting.
        chainId:
          $ref: '#/components/schemas/ChainId'
    ErrorCode:
      type: string
      description: >-
        Documented Velora error code (e.g. `PricingError`, `InvalidInput`,
        `UnsupportedChain`, `StalePriceRoute`, `InvalidSignature`). The set is
        open — handle codes you recognize and fall back to a generic error path
        for everything else. See /api-reference/troubleshooting for known codes.
      example: PricingError

````