Trade API

Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →

A Trade API é um conjunto simples de endpoints em transaction-v1.raydium.io (e alguns caminhos espelhados em api-v3.raydium.io) que fornece uma cotação de swap, constrói uma transação Solana pronta para assinar e a retorna em uma única rodada. É a mesma superfície que a UI do Raydium usa. Use-a quando você quer roteamento Raydium sem agrupar o TS SDK — backends, manipuladores de Blinks, bots de Telegram, apps de terceiros.

Quando usar a Trade API vs o SDK

Você quer…	Use
Integrar swaps em um backend que não pode agrupar pacotes npm (ex: bot Python, serviço Go, serviço Rust)	Trade API
Renderizar um Blink de swap em uma postagem social	Trade API
Construir um app de navegador onde economizar kilobytes importa	Trade API
Incorporar lógica de roteamento dentro de outro programa Solana (CPI)	Nenhum — use `sdk-api/rust-cpi`
Construir um cliente completo tipo DEX com visualização de rota personalizada, sobreposições de gráfico, heurísticas de taxa de prioridade	TS SDK
Precisa de cotação determinística offline sem rodada de rede	TS SDK (com estado de pool local)

O SDK é mais rico; a Trade API é mais simples. Ambos envolvem os mesmos programas CPMM/CLMM/AMM v4 subjacentes, então o swap na cadeia resultante é idêntico.

Os três endpoints

1. `GET /compute/swap-base-in`

Dado um valor de entrada, escolha uma rota e retorne uma cotação.

GET https://transaction-v1.raydium.io/compute/swap-base-in
  ?inputMint=So11111111111111111111111111111111111111112
  &outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
  &amount=1000000000
  &slippageBps=50
  &txVersion=V0

Resposta:

{
  "id": "b2e4...",
  "success": true,
  "version": "V1",
  "data": {
    "swapType": "BaseIn",
    "inputMint":  "So11111111111111111111111111111111111111112",
    "inputAmount":  "1000000000",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputAmount": "165234567",
    "otherAmountThreshold": "164408394",
    "slippageBps": 50,
    "priceImpactPct": 0.0012,
    "referrerAmount": "0",
    "routePlan": [
      { "poolId": "58oQ...", "inputMint": "So11...", "outputMint": "USDC...", "feeAmount": "2500000", "feeMint": "So11..." }
    ]
  }
}

O campo id é um identificador de cotação opaco passado para o próximo endpoint. A cotação é estável por ~30 segundos; além disso, re-cotize.

2. `GET /compute/swap-base-out`

Forma invertida: “Quero receber exatamente N da saída; cotize-me a entrada necessária.”

GET /compute/swap-base-out
  ?inputMint=<MINT_IN>
  &outputMint=<MINT_OUT>
  &amount=<DESIRED_OUTPUT_AMOUNT>
  &slippageBps=50
  &txVersion=V0

Forma de resposta simétrica a swap-base-in; semântica do campo amount inverte.

3. `POST /transaction/swap-base-in` e `/transaction/swap-base-out`

Pega a cotação da etapa 1 e retorna uma transação versionada pronta para assinar:

POST https://transaction-v1.raydium.io/transaction/swap-base-in
Content-Type: application/json

{
  "computeUnitPriceMicroLamports": "50000",
  "swapResponse": { ... cole o objeto data de swap-base-in ... },
  "txVersion": "V0",
  "wallet": "<user_pubkey>",
  "wrapSol": true,
  "unwrapSol": false,
  "inputAccount": "<optional_token_account>",
  "outputAccount": "<optional_token_account>"
}

Resposta:

{
  "id": "9f1c...",
  "success": true,
  "version": "V1",
  "data": [
    { "transaction": "<base64-encoded-versioned-transaction>" }
  ]
}

Múltiplas transações podem ser retornadas se o swap requer setup (ex: criar ATAs, envolver SOL). Assine e envie-as em ordem.

Exemplo mínimo de ponta a ponta (Python)

import base64, requests
from solders.transaction import VersionedTransaction
from solders.keypair import Keypair
from solana.rpc.api import Client

rpc = Client("https://api.mainnet-beta.solana.com")
kp = Keypair.from_bytes(bytes([...]))    # seu signatário

SOL  = "So11111111111111111111111111111111111111112"
USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

quote = requests.get(
    "https://transaction-v1.raydium.io/compute/swap-base-in",
    params={
        "inputMint": SOL, "outputMint": USDC,
        "amount": 1_000_000_000, "slippageBps": 50, "txVersion": "V0",
    },
).json()

built = requests.post(
    "https://transaction-v1.raydium.io/transaction/swap-base-in",
    json={
        "computeUnitPriceMicroLamports": "50000",
        "swapResponse": quote,
        "txVersion": "V0",
        "wallet": str(kp.pubkey()),
        "wrapSol": True,
        "unwrapSol": False,
    },
).json()

for entry in built["data"]:
    raw = base64.b64decode(entry["transaction"])
    tx = VersionedTransaction.from_bytes(raw)
    tx.sign([kp])
    sig = rpc.send_raw_transaction(bytes(tx)).value
    print(f"Sent: {sig}")

Isso são ~20 linhas. O equivalente com o TS SDK é ~30, mas oferece controle mais rico (seletor de rota personalizado, orçamento de Compute Unit por pool, metadados de erro detalhados).

Roteamento e seleção de pool

A Trade API roteia entre todos os programas Raydium (CPMM, CLMM, AMM v4) e escolhe a melhor execução para o tamanho cotado. Características:

Multi-hop suportado. Um swap SOL→USDC pode rotear através de wSOL→JUP→USDC se for mais barato.
Divisão de múltiplos pools do mesmo programa não suportada. Uma cotação única passa por exatamente um caminho; se você quer dividir tamanho entre pools, faça lado cliente (duas cotações, duas txs).
Estável vs concentrado. O roteador prefere usar CLMM quando a liquidez in-range é adequada, recorrendo a CPMM para pares de cauda longa.
Inclusão AMM v4. Pools AMM v4 são incluídos no roteamento mas apenas escolhidos quando oferecem melhor preço que alternativas CPMM/CLMM.

Para forçar roteamento através de um pool específico, use o SDK — a Trade API não expõe um parâmetro de pin de pool.

Parâmetro de referrer

Acrescente &referrer=<wallet_pubkey> ao endpoint compute para tomar um corte de referência de 1% no swap. Veja user-flows/referrals-and-blinks para semântica. Quando presente:

referrerAmount na resposta de cotação é a quantidade absoluta (em mint de entrada) que será roteada para o referrer.
A transação final contém uma transferência de token SPL extra para a ATA do referrer.

Taxas de prioridade

computeUnitPriceMicroLamports na solicitação de build define a taxa de prioridade para a transação retornada. Regra de ouro:

50_000 (0.00005 lamports/CU × 200k CU ≈ 0.00001 SOL): mínimo, bom para momentos sem congestionamento.
200_000: congestionamento moderado.
1_000_000: congestionamento pesado.

Para ajuste adaptativo, chame getRecentPrioritizationFees em seu RPC primeiro e passe a mediana. Veja integration-guides/priority-fee-tuning.

Versões de transação

"V0" retorna uma transação versionada (MessageV0) com uma lookup table para contas comuns. Menor, mais rápida. Recomendado.
"LEGACY" retorna uma transação legada. Maior; use apenas se sua carteira/infra não trata V0.

Formas de erro

A API retorna HTTP 200 com success: false para erros lógicos, HTTP 4xx/5xx para erros de transporte / infraestrutura. Erros lógicos comuns:

"No route found" — nenhum caminho entre os dois mints neste tamanho. Reduza amount ou reconsidere o par.
"Insufficient liquidity" — uma rota existe mas ultrapassaria slippageBps. Amplie slippage.
"Quote expired" — swapResponse tem >30s. Re-cotize.
"Unsupported mint" — mint não está no universo Raydium (não listado, ou em um programa descontinuado).

Limites de taxa

Endpoints de cotação: 120 req/min por IP.
Endpoints de build: 60 req/min por IP (custo mais alto no servidor).
Exceder limites retorna HTTP 429 com cabeçalho Retry-After.

Para maior throughput contacte relações com desenvolvedores do Raydium; chaves de nível agregador estão disponíveis.

Padrão arquitetural para integradores

┌─────────────┐   quote   ┌───────────────┐   build   ┌───────────────┐   sign/send   ┌──────────┐
│ Seu front   │──────────►│ Trade API     │──────────►│ Trade API     │──────────────►│ Solana   │
│   end       │◄──────────│ /compute/...  │◄──────────│ /transaction/ │               │   RPC    │
└─────────────┘           └───────────────┘           └───────────────┘               └──────────┘
                              (stateless)                 (stateless)

Tudo é stateless — a única coisa que você precisa passar entre a chamada de cotação e a chamada de build é o corpo da resposta de cotação em si.

Para onde ir a seguir

sdk-api/typescript-sdk — interface programática mais rica com os mesmos programas subjacentes.
sdk-api/rest-api — endpoints de leitura (info de pool, info de mint) para complementar o lado de escrita da Trade API.
user-flows/swap — fluxo de swap UI de ponta a ponta.
integration-guides/aggregator — padrão para agregadores que rotam através de muitos DEXes.

Fontes:

Endpoints live transaction-v1.raydium.io.
Inspeção de aba de rede da UI Raydium (mesma superfície consumida).

Solana fundamentals

Quick start

SDK & API

Integration guides

Quando usar a Trade API vs o SDK

Os três endpoints

1. `GET /compute/swap-base-in`

2. `GET /compute/swap-base-out`

3. `POST /transaction/swap-base-in` e `/transaction/swap-base-out`

Exemplo mínimo de ponta a ponta (Python)

Roteamento e seleção de pool

Parâmetro de referrer

Taxas de prioridade

Versões de transação

Formas de erro

Limites de taxa

Padrão arquitetural para integradores

Para onde ir a seguir

​Quando usar a Trade API vs o SDK

​Os três endpoints

​1. GET /compute/swap-base-in

​2. GET /compute/swap-base-out

​3. POST /transaction/swap-base-in e /transaction/swap-base-out

​Exemplo mínimo de ponta a ponta (Python)

​Roteamento e seleção de pool

​Parâmetro de referrer

​Taxas de prioridade

​Versões de transação

​Formas de erro

​Limites de taxa

​Padrão arquitetural para integradores

​Para onde ir a seguir

Quando usar a Trade API vs o SDK

Os três endpoints

1. `GET /compute/swap-base-in`

2. `GET /compute/swap-base-out`

3. `POST /transaction/swap-base-in` e `/transaction/swap-base-out`

Exemplo mínimo de ponta a ponta (Python)

Roteamento e seleção de pool

Parâmetro de referrer

Taxas de prioridade

Versões de transação

Formas de erro

Limites de taxa

Padrão arquitetural para integradores

Para onde ir a seguir