openapi: 3.0.3
info:
  title: API de Transações Raydium (Route V2)
  version: 1.0.0
  description: >
    Construtor de transações de swap no lado do servidor para Solana. Esta API
    gera transações de swap serializadas sem exigir que clientes executem uma
    conexão RPC ou o SDK completo do Raydium.


    As respostas seguem um formato de envelope padrão:

    - **Sucesso**: `{ id: string, success: true, data: {...} }`

    - **Erro**: `{ id: string, success: false, msg: string }`
  contact:
    name: Raydium
    url: https://raydium.io
servers:
  - url: https://transaction-v1.raydium.io
    description: Mainnet
  - url: https://transaction-v1-devnet.raydium.io
    description: Devnet
tags:
  - name: Compute
    description: >-
      Endpoints somente leitura para computação de cotação de swap (sem
      construção de transação).
  - name: Transaction
    description: >-
      Construir transações de swap serializadas prontas para assinar e
      transmitir.
paths:
  /compute/swap-base-in:
    get:
      summary: Computar cotação de swap (entrada base)
      description: >
        Calcular o valor de saída esperado ao fazer swap de um valor de entrada
        fixo.

        Útil para exibir uma visualização antes da construção da transação.
      operationId: computeSwapBaseIn
      tags:
        - Compute
      parameters:
        - name: inputMint
          in: query
          required: true
          schema:
            type: string
          description: >-
            Endereço de mint do token de entrada (chave pública codificada em
            base58).
          example: EPjFWdd5Au5WrWSNY8jk5oHE3TkM3TvhEhBNj9xtJzwQ
        - name: outputMint
          in: query
          required: true
          schema:
            type: string
          description: >-
            Endereço de mint do token de saída (chave pública codificada em
            base58).
          example: So11111111111111111111111111111111111111112
        - name: amount
          in: query
          required: true
          schema:
            type: string
          description: >-
            Valor de entrada em lamports (menor unidade de tokens SPL). Deve ser
            uma string de inteiro não negativo.
          example: '1000000'
        - name: slippageBps
          in: query
          required: true
          schema:
            type: string
          description: >-
            Tolerância máxima de slippage em basis points (0–10000). 1 bps =
            0,01%.
          example: '50'
        - name: referrerBps
          in: query
          required: false
          schema:
            type: string
          description: >-
            Taxa de referência opcional em basis points (0–10000). Usada apenas
            se você tiver uma autoridade de referência.
          example: '100'
        - name: txVersion
          in: query
          required: true
          schema:
            type: string
            enum:
              - V0
              - LEGACY
          description: >-
            Versão de transação Solana. V0 usa tabelas de lookup de endereços;
            LEGACY é o formato tradicional.
          example: V0
      responses:
        '200':
          description: Cotação de swap computada com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputeSwapResponse'
        '400':
          description: Parâmetros de entrada inválidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /compute/swap-base-out:
    get:
      summary: Computar cotação de swap (saída base)
      description: >
        Calcular o valor de entrada necessário para atingir um valor de saída
        desejado.

        Útil para swaps onde você conhece a saída alvo.
      operationId: computeSwapBaseOut
      tags:
        - Compute
      parameters:
        - name: inputMint
          in: query
          required: true
          schema:
            type: string
          description: Endereço de mint do token de entrada.
          example: EPjFWdd5Au5WrWSNY8jk5oHE3TkM3TvhEhBNj9xtJzwQ
        - name: outputMint
          in: query
          required: true
          schema:
            type: string
          description: Endereço de mint do token de saída.
          example: So11111111111111111111111111111111111111112
        - name: amount
          in: query
          required: true
          schema:
            type: string
          description: Valor de saída desejado na menor unidade (lamports).
          example: '5000000'
        - name: slippageBps
          in: query
          required: true
          schema:
            type: string
          description: Tolerância máxima de slippage em basis points (0–10000).
          example: '50'
        - name: txVersion
          in: query
          required: true
          schema:
            type: string
            enum:
              - V0
              - LEGACY
          description: Versão de transação Solana.
          example: V0
      responses:
        '200':
          description: Cotação de swap computada com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputeSwapResponse'
        '400':
          description: Parâmetros de entrada inválidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /transaction/swap-base-in:
    post:
      summary: Construir transação de swap (entrada base)
      description: |
        Gerar uma transação de swap serializada para um valor de entrada fixo.
        Requer uma resposta bem-sucedida de `/compute/swap-base-in`.
      operationId: buildSwapTransactionBaseIn
      tags:
        - Transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildTransactionRequest'
      responses:
        '200':
          description: Transação serializada construída com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: Corpo da solicitação inválido ou estado de computação inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /transaction/swap-base-out:
    post:
      summary: Construir transação de swap (saída base)
      description: |
        Gerar uma transação de swap serializada para um valor de saída desejado.
        Requer uma resposta bem-sucedida de `/compute/swap-base-out`.
      operationId: buildSwapTransactionBaseOut
      tags:
        - Transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildTransactionRequest'
      responses:
        '200':
          description: Transação serializada construída com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: Corpo da solicitação inválido ou estado de computação inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ComputeSwapResponse:
      type: object
      properties:
        id:
          type: string
          description: Identificador único de solicitação (UUID).
          example: 550e8400-e29b-41d4-a716-446655440000
        success:
          type: boolean
          description: Se a computação foi bem-sucedida.
          example: true
        version:
          type: string
          description: Versão de resposta da API.
          example: V1
        data:
          type: object
          description: Resultado da computação de swap.
          properties:
            inputAmount:
              type: string
              description: Valor de entrada na menor unidade.
            outputAmount:
              type: string
              description: Valor de saída esperado (considerando slippage).
            priceImpact:
              type: string
              description: 'Percentual de impacto de preço (ex: "0,5" para 0,5%).'
            routes:
              type: array
              description: Matriz de rotas de swap e pools utilizados.
              items:
                type: object
    TransactionResponse:
      type: object
      properties:
        id:
          type: string
          description: Identificador único de solicitação.
          example: 550e8400-e29b-41d4-a716-446655440000
        success:
          type: boolean
          description: Se a construção da transação foi bem-sucedida.
          example: true
        version:
          type: string
          example: V1
        data:
          type: object
          description: Dados da transação.
          properties:
            transaction:
              type: string
              description: Transação versionada codificada em base64 (pronta para assinar).
            addressLookupTableAddresses:
              type: array
              description: Endereços da tabela de pesquisa de endereços (se txVersion=V0).
              items:
                type: string
    BuildTransactionRequest:
      type: object
      required:
        - wallet
        - swapResponse
        - txVersion
        - computeUnitPriceMicroLamports
      properties:
        wallet:
          type: string
          description: Endereço da carteira assinante (base58).
          example: '11111111111111111111111111111111'
        swapResponse:
          type: object
          description: O objeto de resposta completo do endpoint de computação.
          properties:
            id:
              type: string
            success:
              type: boolean
            version:
              type: string
            data:
              type: object
        txVersion:
          type: string
          enum:
            - V0
            - LEGACY
          description: Versão da transação Solana.
          example: V0
        computeUnitPriceMicroLamports:
          type: string
          description: >-
            Preço da unidade de computação em micro-lamports (para taxas de
            prioridade).
          example: '1000'
        wrapSol:
          type: boolean
          description: Se deve fazer wrap de SOL se a entrada for SOL nativo.
          example: false
        unwrapSol:
          type: boolean
          description: Se deve fazer unwrap de WSOL para SOL na saída.
          example: false
        inputAccount:
          type: string
          description: >-
            Endereço da conta de token opcional para entrada. Obrigatório se não
            estiver fazendo wrap de SOL.
          example: TokenAccount1111111111111111111111111111111111
        outputAccount:
          type: string
          description: Endereço da conta de token opcional para saída.
          example: TokenAccount2222222222222222222222222222222222
        jitoInfo:
          type: object
          description: Parâmetros opcionais de bundle Jito para proteção contra MEV.
          properties:
            address:
              type: string
              description: Endereço de submissão de bundle Jito.
            amount:
              type: string
              description: Valor da dica do bundle em lamports.
        referrerWallet:
          type: string
          description: Endereço da carteira referenciadora opcional para coleta de taxas.
          example: ReferrerWallet1111111111111111111111111111111111
    ErrorResponse:
      type: object
      properties:
        id:
          type: string
          description: Identificador único da solicitação.
        success:
          type: boolean
          example: false
        version:
          type: string
          example: V1
        msg:
          type: string
          description: >-
            Código de mensagem de erro (p. ex., REQ_SLIPPAGE_BPS_ERROR,
            REQ_WALLET_ERROR).