Skip to main content
API docs by Redocly

Referral Smart Contract (1.0.0)

Download OpenAPI specification:Download

URL: https://bitcoin.me

The Referral Smart Contract enables dApp integrators to earn referral fees on swaps routed through their application. It executes a normal router swap and then splits the final output between the referral address and the user.

Overview

The Referral contract provides:

  • On-chain Referral Fees: Your dApp earns fees directly on-chain for swaps it routes
  • Automatic Output Splitting: After swap, output is split between referral and user
  • Configurable Percentage: Referral percentage from 0.1% to 5% (base 100,000)

How Output Splitting Works

After the swap output is determined:

  1. referral_amount = amount_out_total * referral_percentage / 100000
  2. destination_amount = amount_out_total - referral_amount
  • Referral amount → sent to your referral_address
  • User amount → sent to amount_out_destination (or caller if not provided)

Referral Percentage Format

referral_percentage uses a base of 100_000:

Value Percentage
100 0.1%
1_000 1.0%
5_000 5.0% (max)

Quotation Flow (Best Practice)

Before sending the swap transaction, request a quotation using token asset IDs:

Endpoint: POST https://api.bitcoin.me/quotation

curl -X POST https://api.bitcoin.me/quotation \
  -H "Content-Type: application/json" \
  -d '{
    "amountIn": "1000",
    "tokenIn": "KLV",
    "tokenOut": "KFI"
  }'

Notes:

  • amountIn must be a string
  • tokenIn and tokenOut must be token asset IDs/tickers expected by the quotation API
  • Use the quotation response to set amount_out_min with common DEX slippage best practices (for example, apply a configurable slippage tolerance and never use zero protection in production)

Suggested Integration Sequence

  1. User selects input/output tokens and amount
  2. Frontend calls quotation API
  3. Frontend computes amount_out_min based on quote and slippage
  4. Frontend submits swap transaction with your referral address, referral percentage, and user payment in token_in
  5. Contract executes swap and splits output

Endpoints

Write operations that modify contract state

Swap with Referral

Executes a router swap and splits the final output between the referral address and the destination address.

How it works:

  1. Receives the swap parameters along with referral configuration
  2. Executes the swap through the router
  3. Calculates the referral fee from the total output
  4. Sends the referral amount to referral_address
  5. Sends the remaining amount to amount_out_destination (or the caller if not provided)

Referral Fee Calculation:

  • referral_amount = amount_out_total * referral_percentage / 100000
  • destination_amount = amount_out_total - referral_amount

Referral Percentage: Uses a base of 100_000 — valid range is 100 (0.1%) to 5_000 (5.0%)

Payment: The input token amount to be swapped (sent as transaction value)

Request Body schema: application/json
required
scAddress
required
string

Referral contract address

funcName
required
string
Value: "swap"
args
required
Array of strings

Arguments:

  • referral_address (ManagedAddress): Address that receives the referral fee
  • referral_percentage (u64): Referral fee percentage (base 100,000 — e.g., 1000 = 1.0%)
  • token_in (TokenIdentifier): Input token identifier
  • token_out (TokenIdentifier): Output token identifier
  • amount_out_min (BigUint): Minimum acceptable output amount (slippage protection)
  • amount_out_destination (ManagedAddress, optional): Address to receive user output (defaults to caller)

Responses

Request samples

Content type
application/json
Example
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgqjd9k34hzy53lsreq4drqkwfedqvtqen3x04sevtrjj",
  • "funcName": "swap",
  • "args": [
    ],
  • "value": "KLV=1000"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}