Python (SDK)

from compass_api_sdk import CompassAPI, models


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.earn.earn_swap(token_in="USDC", token_out="USDT", amount_in="0.01", owner="0x06A9aF046187895AcFc7258450B15397CAc67400", chain=models.Chain.BASE, slippage="0.5", gas_sponsorship=False)

    # Handle response
    print(res)

import { CompassApiSDK } from "@compass-labs/api-sdk";

const compassApiSDK = new CompassApiSDK({
  apiKeyAuth: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await compassApiSDK.earn.earnSwap({
    tokenIn: "USDC",
    tokenOut: "USDT",
    amountIn: "0.01",
    slippage: "0.5",
    owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
    chain: "base",
    gasSponsorship: false,
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.compasslabs.ai/v2/earn/swap \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "owner": "0x06A9aF046187895AcFc7258450B15397CAc67400",
  "chain": "base",
  "token_in": "USDC",
  "token_out": "USDT",
  "amount_in": "0.01",
  "slippage": "0.5",
  "gas_sponsorship": false
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    owner: '0x06A9aF046187895AcFc7258450B15397CAc67400',
    chain: 'base',
    token_in: 'USDC',
    token_out: 'USDT',
    amount_in: '0.01',
    slippage: '0.5',
    gas_sponsorship: false
  })
};

fetch('https://api.compasslabs.ai/v2/earn/swap', 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.compasslabs.ai/v2/earn/swap",
  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([
    'owner' => '0x06A9aF046187895AcFc7258450B15397CAc67400',
    'chain' => 'base',
    'token_in' => 'USDC',
    'token_out' => 'USDT',
    'amount_in' => '0.01',
    'slippage' => '0.5',
    'gas_sponsorship' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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.compasslabs.ai/v2/earn/swap"

	payload := strings.NewReader("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"base\",\n  \"token_in\": \"USDC\",\n  \"token_out\": \"USDT\",\n  \"amount_in\": \"0.01\",\n  \"slippage\": \"0.5\",\n  \"gas_sponsorship\": false\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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.compasslabs.ai/v2/earn/swap")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"base\",\n  \"token_in\": \"USDC\",\n  \"token_out\": \"USDT\",\n  \"amount_in\": \"0.01\",\n  \"slippage\": \"0.5\",\n  \"gas_sponsorship\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.compasslabs.ai/v2/earn/swap")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"base\",\n  \"token_in\": \"USDC\",\n  \"token_out\": \"USDT\",\n  \"amount_in\": \"0.01\",\n  \"slippage\": \"0.5\",\n  \"gas_sponsorship\": false\n}"

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

{
  "estimated_amount_out": "2485.123456",
  "transaction": {
    "chainId": "0x2105",
    "data": "0x8d80ff0a0000000000000000000000000000000000000000000000000000000000000020",
    "from": "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
    "gas": "0x7a120",
    "maxFeePerGas": "0x59682f00",
    "maxPriorityFeePerGas": "0x3b9aca00",
    "nonce": "0x5",
    "to": "0x6B90E8B4E3E971E74C1A47a3a20976377E2dB4b1",
    "value": "0x0"
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Earn

Swap tokens within Earn Account

Swap tokens within an Earn Account.

Use this endpoint to exchange one token for another without transferring funds out of the Earn Account.

The swap executes atomically within the Earn Account and can be combined with other actions using the bundle endpoint. For example, swap ETH to USDC, then deposit USDC into a vault—all in one transaction.

Returns either an unsigned transaction (when gas_sponsorship=false) or EIP-712 typed data for off-chain signing (when gas_sponsorship=true). For gas-sponsored swaps, submit the signed typed data to /gas_sponsorship/prepare.

POST

earn

swap

Python (SDK)

from compass_api_sdk import CompassAPI, models


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.earn.earn_swap(token_in="USDC", token_out="USDT", amount_in="0.01", owner="0x06A9aF046187895AcFc7258450B15397CAc67400", chain=models.Chain.BASE, slippage="0.5", gas_sponsorship=False)

    # Handle response
    print(res)

import { CompassApiSDK } from "@compass-labs/api-sdk";

const compassApiSDK = new CompassApiSDK({
  apiKeyAuth: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await compassApiSDK.earn.earnSwap({
    tokenIn: "USDC",
    tokenOut: "USDT",
    amountIn: "0.01",
    slippage: "0.5",
    owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
    chain: "base",
    gasSponsorship: false,
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.compasslabs.ai/v2/earn/swap \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "owner": "0x06A9aF046187895AcFc7258450B15397CAc67400",
  "chain": "base",
  "token_in": "USDC",
  "token_out": "USDT",
  "amount_in": "0.01",
  "slippage": "0.5",
  "gas_sponsorship": false
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    owner: '0x06A9aF046187895AcFc7258450B15397CAc67400',
    chain: 'base',
    token_in: 'USDC',
    token_out: 'USDT',
    amount_in: '0.01',
    slippage: '0.5',
    gas_sponsorship: false
  })
};

fetch('https://api.compasslabs.ai/v2/earn/swap', 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.compasslabs.ai/v2/earn/swap",
  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([
    'owner' => '0x06A9aF046187895AcFc7258450B15397CAc67400',
    'chain' => 'base',
    'token_in' => 'USDC',
    'token_out' => 'USDT',
    'amount_in' => '0.01',
    'slippage' => '0.5',
    'gas_sponsorship' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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.compasslabs.ai/v2/earn/swap"

	payload := strings.NewReader("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"base\",\n  \"token_in\": \"USDC\",\n  \"token_out\": \"USDT\",\n  \"amount_in\": \"0.01\",\n  \"slippage\": \"0.5\",\n  \"gas_sponsorship\": false\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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.compasslabs.ai/v2/earn/swap")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"base\",\n  \"token_in\": \"USDC\",\n  \"token_out\": \"USDT\",\n  \"amount_in\": \"0.01\",\n  \"slippage\": \"0.5\",\n  \"gas_sponsorship\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.compasslabs.ai/v2/earn/swap")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"base\",\n  \"token_in\": \"USDC\",\n  \"token_out\": \"USDT\",\n  \"amount_in\": \"0.01\",\n  \"slippage\": \"0.5\",\n  \"gas_sponsorship\": false\n}"

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

{
  "estimated_amount_out": "2485.123456",
  "transaction": {
    "chainId": "0x2105",
    "data": "0x8d80ff0a0000000000000000000000000000000000000000000000000000000000000020",
    "from": "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
    "gas": "0x7a120",
    "maxFeePerGas": "0x59682f00",
    "maxPriorityFeePerGas": "0x3b9aca00",
    "nonce": "0x5",
    "to": "0x6B90E8B4E3E971E74C1A47a3a20976377E2dB4b1",
    "value": "0x0"
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

x-api-key

string

header

required

Your Compass API Key. Get your key here.

Body

application/json

Request model for swap endpoint.

Inherits swap params and adds context fields (owner, chain, gas_sponsorship).

token_in

string

default:USDC

required

Token to sell (input). Provide a token symbol from a limited set (e.g., 'USDC') or any token address.

Examples:

"USDC"

"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

token_out

string

default:USDT

required

Token to buy (output). Provide a token symbol from a limited set (e.g., 'USDT') or any token address.

Examples:

"USDT"

"0xdAC17F958D2ee523a2206206994597C13D831ec7"

amount_in

default:0.01

required

Human-readable amount of token_in to swap (token units, not wei).

Required range: x > 0

Example:

1.5

owner

string

default:0x06A9aF046187895AcFc7258450B15397CAc67400

required

The owner's wallet address.

Example:

"0x06A9aF046187895AcFc7258450B15397CAc67400"

chain

enum<string>

default:base

required

Target blockchain network where the swap will execute.

Available options:

base,

ethereum,

arbitrum,

hyperevm,

tempo,

bsc

Example:

"base"

action_type

string

default:V2_SWAP

Action type identifier for swap operations.

Allowed value: "V2_SWAP"

slippage

default:0.5

Maximum slippage tolerance as a percentage (e.g., 0.5 = 0.5%).

Example:

0.5

gas_sponsorship

boolean

default:false

Optionally request gas sponsorship. If true, EIP-712 typed data will be returned that must be signed by the owner and submitted to the 'Prepare gas-sponsored transaction' endpoint (/gas_sponsorship/prepare).

Example:

false

Response

Successful Response

estimated_amount_out

string

required

Estimated amount of output token received from the swap.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

transaction

UnsignedTransaction · object | null

Unsigned transaction for direct execution. Present when gas_sponsorship=false.

Show child attributes

Example:

{
  "chainId": "0x2105",
  "data": "0x1688f0b900000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000675f4a3d",
  "from": "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
  "gas": "0x7a120",
  "maxFeePerGas": "0x59682f00",
  "maxPriorityFeePerGas": "0x3b9aca00",
  "nonce": "0x5",
  "to": "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67",
  "value": "0x0"
}

eip_712

BatchedSafeOperationsResponse · object | null

EIP-712 typed data for gas-sponsored execution. Present when gas_sponsorship=true.

Show child attributes

Example:

{
  "domain": {
    "chainId": 8453,
    "verifyingContract": "0x6B90E8B4E3E971E74C1A47a3a20976377E2dB4b1"
  },
  "message": {
    "baseGas": "0",
    "data": "0x8d80ff0a0000000000000000000000000000000000000000000000000000000000000020",
    "gasPrice": "0",
    "gasToken": "0x0000000000000000000000000000000000000000",
    "nonce": "7",
    "operation": 1,
    "refundReceiver": "0x0000000000000000000000000000000000000000",
    "safeTxGas": "0",
    "to": "0x93C23AAE4793C14D6DF35D2A2A2234204e1559dA",
    "value": "0"
  },
  "primaryType": "SafeTx",
  "types": {
    "EIP712Domain": [
      { "name": "chainId", "type": "uint256" },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "SafeTx": [
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" },
      { "name": "data", "type": "bytes" },
      { "name": "operation", "type": "uint8" },
      { "name": "safeTxGas", "type": "uint256" },
      { "name": "baseGas", "type": "uint256" },
      { "name": "gasPrice", "type": "uint256" },
      { "name": "gasToken", "type": "address" },
      {
        "name": "refundReceiver",
        "type": "address"
      },
      { "name": "nonce", "type": "uint256" }
    ]
  }
}

Manage earn position Execute multiple earn actions

⌘I