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

# Generate metadata for Swap application

> Creates metadata configuration for a token swap application. Currently supports LFJ and Pangolin protocols. The generated metadata can be used to create widgets for token swaps on supported blockchain networks.



## OpenAPI

````yaml /api-reference/openapi.json post /action/builders/swap
openapi: 3.0.0
info:
  title: Relayer
  description: >-
    Relayer API — Kit-based crypto infrastructure for OTC exchange, wallet
    signing, payouts, and widget actions.
  version: '1.0'
  contact: {}
servers:
  - url: https://testnet.relayer.fi/v1
    description: Sandbox (testnet wallets, no real fiat)
  - url: https://api.relayer.fi/v1
    description: Production (mainnet wallets, regulated fiat rails)
security:
  - api-key: []
tags:
  - name: 'Action: Builders'
    description: Transaction metadata builders
  - name: 'Action: Directory'
    description: Widget directory
  - name: 'Action: Execute'
  - name: 'Action: Tokens'
    description: Token lists per chain/protocol
  - name: Addresses
  - name: Agents
  - name: App
    description: Application endpoints
  - name: 'Payout: Accounts'
    description: Payment execution
  - name: 'Payout: Off-ramp'
  - name: 'Payout: On-ramp'
  - name: 'Payout: Orders'
  - name: 'Payout: Recipients'
    description: Beneficiary management
  - name: Signing - Passkeys
  - name: Signing - Recovery
  - name: Signing Approvals
    description: Transaction signing approvals
  - name: Signing Policies
    description: Signing policy management
  - name: Transactions
    description: Transaction signing and broadcasting
  - name: Wallets
    description: Wallet and address management
paths:
  /action/builders/swap:
    post:
      tags:
        - 'Action: Builders'
      summary: Generate metadata for Swap application
      description: >-
        Creates metadata configuration for a token swap application. Currently
        supports LFJ and Pangolin protocols. The generated metadata can be used
        to create widgets for token swaps on supported blockchain networks.
      operationId: WidgetMetadataController_generateSwapMetadata
      parameters: []
      requestBody:
        required: true
        description: Parameters for generating swap metadata
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapMetadataDto'
            examples:
              LFJ Swap:
                value:
                  protocol: lfj
                  chainName: avalanche
                  fromToken: AVAX
                  toToken: JOE
                  routerAddress: '0xb00D916688FEE4aB6646994104E1441446947fc9'
                  slippageTolerance: 0.5
                description: Swap AVAX to JOE using LFJ protocol on Avalanche
              Pangolin Swap:
                value:
                  protocol: pangolin
                  chainName: avalanche
                  fromToken: AVAX
                  toToken: PNG
                  routerAddress: '0xb00D916688FEE4aB6646994104E1441446947fc9'
                  slippageTolerance: 0.5
                description: Swap AVAX to PNG using Pangolin protocol on Avalanche
      responses:
        '200':
          description: Swap metadata generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  metadata:
                    type: object
                    description: >-
                      Generated metadata object containing all swap
                      configuration
        '400':
          description: Bad Request - Invalid parameters provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 400
                  message:
                    type: array
                    items:
                      type: string
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDto'
        '403':
          description: >-
            Forbidden - Insufficient permissions. Requires INTERNAL or
            INTEGRATOR scope (ADMIN scope also allowed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDto'
        '500':
          description: Internal Server Error - Failed to generate metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDto'
      security:
        - api-key: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl -X POST https://api.relayer.fi/v1/action/builders/swap \
              -H "Authorization: ApiKey $RELAYER_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "tokenIn":  "0xA0b86a33...",
                "tokenOut": "0xC02aaA39...",
                "chain":    "base",
                "title":    "Swap USDC → WETH"
              }'
        - lang: TypeScript
          label: Node.js
          source: >-
            const response = await
            fetch("https://api.relayer.fi/v1/action/builders/swap", {
              method: "POST",
              headers: {
                Authorization: `ApiKey ${process.env.RELAYER_API_KEY}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                tokenIn:  "0xA0b86a33...",
                tokenOut: "0xC02aaA39...",
                chain:    "base",
                title:    "Swap USDC → WETH",
              }),
            });

            const { data } = await response.json();

            // data — canonical swap widget metadata. Use the widget metadata
            URL

            // in your frontend's <Widget url=... /> component.
components:
  schemas:
    SwapMetadataDto:
      type: object
      properties:
        protocol:
          type: string
          description: Protocol name
          example: lfj
        chainName:
          type: string
          description: Blockchain name
          example: avalanche
        fromToken:
          type: string
          description: Input token
          example: AVAX
        toToken:
          type: string
          description: Output token
          example: JOE
        routerAddress:
          type: string
          description: KOL Router contract address
          example: '0x123abc456def789012345678901234567890abcd'
        slippageTolerance:
          type: number
          description: Slippage tolerance (percentage)
          example: 0.5
      required:
        - protocol
        - chainName
        - fromToken
        - toToken
        - routerAddress
        - slippageTolerance
    ApiResponseDto:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
        statusCode:
          type: number
        timestamp:
          type: string
        path:
          type: string
        traceId:
          type: string
      required:
        - success
        - message
        - statusCode
        - timestamp
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use this format: `ApiKey <your_api_key>`'

````