Trade tokens (buy or sell)

curl --request POST \
  --url https://api.tokenlayer.network/functions/v1/trade-token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokenId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chainSlug": "base-sepolia",
  "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "token_referral": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "buyAmountUSD": 1,
  "buyAmountToken": 1000,
  "sellAmountToken": 1000,
  "sellAmountUSD": 1
}
'

import requests

url = "https://api.tokenlayer.network/functions/v1/trade-token"

payload = {
    "tokenId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chainSlug": "base-sepolia",
    "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "token_referral": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "buyAmountUSD": 1,
    "buyAmountToken": 1000,
    "sellAmountToken": 1000,
    "sellAmountUSD": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    chainSlug: 'base-sepolia',
    userAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    token_referral: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    buyAmountUSD: 1,
    buyAmountToken: 1000,
    sellAmountToken: 1000,
    sellAmountUSD: 1
  })
};

fetch('https://api.tokenlayer.network/functions/v1/trade-token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tokenlayer.network/functions/v1/trade-token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'tokenId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'chainSlug' => 'base-sepolia',
    'userAddress' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    'token_referral' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    'buyAmountUSD' => 1,
    'buyAmountToken' => 1000,
    'sellAmountToken' => 1000,
    'sellAmountUSD' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tokenlayer.network/functions/v1/trade-token"

	payload := strings.NewReader("{\n  \"tokenId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"chainSlug\": \"base-sepolia\",\n  \"userAddress\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"token_referral\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"buyAmountUSD\": 1,\n  \"buyAmountToken\": 1000,\n  \"sellAmountToken\": 1000,\n  \"sellAmountUSD\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tokenlayer.network/functions/v1/trade-token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokenId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"chainSlug\": \"base-sepolia\",\n  \"userAddress\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"token_referral\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"buyAmountUSD\": 1,\n  \"buyAmountToken\": 1000,\n  \"sellAmountToken\": 1000,\n  \"sellAmountUSD\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tokenlayer.network/functions/v1/trade-token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tokenId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"chainSlug\": \"base-sepolia\",\n  \"userAddress\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"token_referral\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"buyAmountUSD\": 1,\n  \"buyAmountToken\": 1000,\n  \"sellAmountToken\": 1000,\n  \"sellAmountUSD\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "transaction": {
    "to": "<string>",
    "data": "<string>",
    "value": "<string>",
    "gasLimit": "<string>",
    "chain": "base-sepolia"
  }
}

{
  "success": false,
  "error": "<string>"
}

{
  "success": false,
  "error": "<string>"
}

{
  "success": false,
  "error": "<string>"
}

Trading

Trade tokens (buy or sell)

Prepares a transaction to buy or sell tokens. Supports multiple trade types:

Buy exact input: Spend specific USD amount
Buy exact output: Receive specific token amount
Sell exact input: Sell specific token amount
Sell exact output: Receive specific USD amount

Automatically uses RobinSwap or UniswapV3 based on token graduation status.

Anti-Sniping & Initial Buy Fees:

The first 6 seconds of trading (equivalent in blocks for each chain) has increased fees to prevent sniping
Fees start at 80% and decrease linearly to 1% over the first 6 seconds worth of blocks
This fee structure applies to all initial purchases, including the first buyer
The quoter automatically includes these fees in all price quotes, so the amounts returned reflect the actual cost including anti-sniping fees
After the initial 6-second window, normal trading fees apply

USD Rewards Attribution:

Builder attribution: Set custom builder fees (in basis points) to earn USD rewards on transactions
Token referral: Enable affiliate programs by specifying referral addresses for token trades
USD rewards are processed in real-time on-chain with no third parties involved
Token referrals have no additional cost to users - enabling affiliate programs onchain

POST

trade-token

Trade tokens (buy or sell)

curl --request POST \
  --url https://api.tokenlayer.network/functions/v1/trade-token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokenId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chainSlug": "base-sepolia",
  "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "token_referral": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "buyAmountUSD": 1,
  "buyAmountToken": 1000,
  "sellAmountToken": 1000,
  "sellAmountUSD": 1
}
'

import requests

url = "https://api.tokenlayer.network/functions/v1/trade-token"

payload = {
    "tokenId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chainSlug": "base-sepolia",
    "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "token_referral": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "buyAmountUSD": 1,
    "buyAmountToken": 1000,
    "sellAmountToken": 1000,
    "sellAmountUSD": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    chainSlug: 'base-sepolia',
    userAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    token_referral: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    buyAmountUSD: 1,
    buyAmountToken: 1000,
    sellAmountToken: 1000,
    sellAmountUSD: 1
  })
};

fetch('https://api.tokenlayer.network/functions/v1/trade-token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tokenlayer.network/functions/v1/trade-token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'tokenId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'chainSlug' => 'base-sepolia',
    'userAddress' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    'token_referral' => '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    'buyAmountUSD' => 1,
    'buyAmountToken' => 1000,
    'sellAmountToken' => 1000,
    'sellAmountUSD' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tokenlayer.network/functions/v1/trade-token"

	payload := strings.NewReader("{\n  \"tokenId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"chainSlug\": \"base-sepolia\",\n  \"userAddress\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"token_referral\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"buyAmountUSD\": 1,\n  \"buyAmountToken\": 1000,\n  \"sellAmountToken\": 1000,\n  \"sellAmountUSD\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tokenlayer.network/functions/v1/trade-token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokenId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"chainSlug\": \"base-sepolia\",\n  \"userAddress\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"token_referral\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"buyAmountUSD\": 1,\n  \"buyAmountToken\": 1000,\n  \"sellAmountToken\": 1000,\n  \"sellAmountUSD\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tokenlayer.network/functions/v1/trade-token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tokenId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"chainSlug\": \"base-sepolia\",\n  \"userAddress\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"token_referral\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n  \"buyAmountUSD\": 1,\n  \"buyAmountToken\": 1000,\n  \"sellAmountToken\": 1000,\n  \"sellAmountUSD\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "transaction": {
    "to": "<string>",
    "data": "<string>",
    "value": "<string>",
    "gasLimit": "<string>",
    "chain": "base-sepolia"
  }
}

{
  "success": false,
  "error": "<string>"
}

{
  "success": false,
  "error": "<string>"
}

{
  "success": false,
  "error": "<string>"
}

Authorizations

Authorization

string

header

required

JWT token or API key

Body

application/json

tokenId

string<uuid>

required

chainSlug

enum<string>

required

Blockchain identifier. Supported chains: solana, solana-devnet, arbitrum, base, base-sepolia, avalanche, op-bnb, bnb, bnb-testnet, ethereum, monad, unichain, unichain-testnet, abstract, polygon, zksync, zksync-testnet

Available options:

solana,

solana-devnet,

arbitrum,

base,

base-sepolia,

avalanche,

op-bnb,

bnb,

bnb-testnet,

ethereum,

monad,

unichain,

unichain-testnet,

abstract,

polygon,

zksync,

zksync-testnet

Example:

"base-sepolia"

direction

enum<string>

required

Available options:

buy,

sell

userAddress

string

User wallet address (optional - if not provided, will use user's Privy wallet from user_wallets table)

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

builder

object

Builder attribution information (optional). Includes address and fee in bps.

Show child attributes

token_referral

string

Token referral address for attribution (optional - defaults to zero address). Used to attribute referral fees to a specific address.

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

buyAmountUSD

number

Required range: x > 0

buyAmountToken

Token amount to buy (number for regular amounts, string for exact wei values at 100%)

Required range: x > 0

Example:

1000

sellAmountToken

Token amount to sell (number for regular amounts, string for exact wei values at 100%)

Required range: x > 0

Example:

1000

sellAmountUSD

number

Required range: x > 0

Response

Successful response

success

enum<boolean>

required

Available options:

true

transaction

object

required

Show child attributes

About

Onboarding

Earn

Integrations

API Reference

Trade tokens (buy or sell)

Authorizations

Body

Response