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.

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

curl --request POST \
  --url https://yppncslmsswqydhhgygz.supabase.co/functions/v1/trade-token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokenId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chainSlug": "base-sepolia",
  "direction": "buy",
  "userAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "builder": {
    "code": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "fee": 50
  },
  "token_referral": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "buyAmountUSD": 1,
  "buyAmountToken": 1,
  "sellAmountToken": 1,
  "sellAmountUSD": 1
}
'

200

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

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-devnet, base, base-sepolia, avalanche, bnb, bnb-testnet, unichain, unichain-testnet, abstract, polygon, zkSync, zkSync-testnet

Available options: solana-devnet, base, base-sepolia, avalanche, bnb, bnb-testnet, 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)

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.

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

buyAmountUSD · number

Required range: x > 0

buyAmountToken · number

Required range: x > 0

sellAmountToken · number

Required range: x > 0

sellAmountUSD · number

Required range: x > 0

Response

200

application/json

Successful response

success · enum<boolean> · required

Available options: true, false

transaction · object · required

Show child attributes