Skip to main content
API docs by Redocly

Router Smart Contract (1.0.0)

Download OpenAPI specification:Download

URL: https://defi.bitcoin.me

The Router Smart Contract serves as a convenient tool for efficiently managing and monitoring Pair contracts in a decentralized environment. It enables the deployer to easily keep track of the existing Pair contracts and offers a wide array of settings functions that make the management of the liquidity pools much easier.

Overview

The Router contract provides:

  • Pair Management: Create and manage liquidity pairs
  • LP Token Issuance: Issue LP tokens for liquidity providers
  • Multi-Pair Swaps: Execute multiple swaps in a single transaction
  • User Pair Creation: Allow users to create their own trading pairs

How Users Create a Pair

  1. Create the Pair: Use createPair endpoint to create the liquidity pair
  2. Issue LP Token: Use issueLpToken endpoint to create the LP token
  3. Add Liquidity: Call addInitialLiquidity on the pair, providing a value greater than configured in configEnableByUserParameters
  4. Lock Tokens: After adding initial liquidity, lock the received tokens using lockTokens from Simple-Lock contract. The lock period must be equal to or greater than the minimum configured. After locking, the user receives an SFT that can be used to redeem tokens after the lock period
  5. Enable Swap: To activate swap on the created pair, send the SFT received from lockTokens to setSwapEnabledByUser. The Router validates the value and lock period and returns the SFT to the user

Endpoints

Write operations that modify contract state

Create Pair

Creates a new liquidity pair and returns the pair contract address.

Process:

  1. Validates the token pair
  2. Deploys a new Pair contract based on the template
  3. Returns the new pair contract address in the response data

Response Decoding: The returned address is hex-encoded and needs to be decoded using the Klever decoder.

Example Response:

Raw: 00000000000000000500b7b4a14e4567a64b122ee61b8717ae11e210809ac3e6
Decoded: klv1qqqqqqqqqqqqqpgqk762znj9v7nyky3wucdcw9awz83ppqy6c0nqhe2qaz
Request Body schema: application/json
required
scAddress
required
string

Router contract address

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

Arguments:

  • first_token_id (TokenIdentifier): First token identifier
  • second_token_id (TokenIdentifier): Second token identifier

Responses

Request samples

Content type
application/json
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgq9fywm4wqawy8udszd3l66hs9vktdtl73c0nqwl5hlk",
  • "funcName": "createPair",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}

Issue LP Token

Creates the LP token that will be distributed to users who add liquidity to the pool.

Process:

  1. Validates the pair exists
  2. Creates a new LP token with the specified name and ticker
  3. Assigns the token to the pair contract

Prerequisites:

  • The pair must be created first using createPair
  • Caller must be the pair owner or have appropriate permissions

Note: After issuing the LP token, you need to set the local roles using setLocalRoles to allow minting.

Request Body schema: application/json
required
scAddress
required
string

Router contract address

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

Arguments:

  • pair_address (ManagedAddress): Address of the pair contract
  • lp_token_display_name (ManagedBuffer): Display name for the LP token
  • lp_token_ticker (ManagedBuffer): Ticker symbol for the LP token

Responses

Request samples

Content type
application/json
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgq9fywm4wqawy8udszd3l66hs9vktdtl73c0nqwl5hlk",
  • "funcName": "issueLpToken",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}

Set Swap Enabled By User

Allows the creator of a pair to activate the swap functionality for that pair.

Process:

  1. After adding initial liquidity (addInitialLiquidity), the user receives LP tokens
  2. These LP tokens must be locked in the Simple-Lock contract
  3. After locking, the user receives an SFT (Semi-Fungible Token)
  4. To activate swap, send the SFT to this endpoint
  5. The Router validates the value and lock period
  6. The SFT is returned to the user after validation

Requirements:

  • The SFT must have a value greater than min_locked_token_value
  • The lock period must be greater than min_lock_period_epochs
  • Both values are configured via configEnableByUserParameters

Payment: The SFT received from locking LP tokens

Request Body schema: application/json
required
scAddress
required
string

Router contract address

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

Arguments:

  • pair_address (ManagedAddress): Address of the pair to enable
value
required
string

SFT payment from Simple-Lock

Responses

Request samples

Content type
application/json
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgq9fywm4wqawy8udszd3l66hs9vktdtl73c0nqwl5hlk",
  • "funcName": "setSwapEnabledByUser",
  • "args": [
    ],
  • "value": "LOCK-2U1O/1=1000000"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}

Multi Pair Swap

Allows users to execute a list of swaps in a single transaction, routing through multiple pairs.

Use Case: When there's no direct pair between two tokens, you can route through intermediate pairs. For example, to swap KFI to ZART when only KFI-KLV and KLV-ZART pairs exist.

Swap Parameters (for each swap):

  • pair_address: The liquidity pair contract address
  • function: Swap type - swapTokensFixedInput or swapTokensFixedOutput
  • token_wanted: The token to receive from the swap
  • amount_wanted: The amount of token_wanted to receive

Supported Functions:

  • swapTokensFixedInput: Fixed input amount, variable output
  • swapTokensFixedOutput: Variable input, fixed output amount

Note: You can mix swapTokensFixedInput and swapTokensFixedOutput in the same multi-swap transaction.

Request Body schema: application/json
required
scAddress
required
string

Router contract address

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

Arguments (repeated for each swap in the route):

  • pair_address (ManagedAddress): Pair contract address
  • function (string): "swapTokensFixedInput" or "swapTokensFixedOutput"
  • token_wanted (TokenIdentifier): Output token
  • amount_wanted (BigUint): Minimum/exact output amount
value
required
string

Initial token payment

Responses

Request samples

Content type
application/json
Example
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgq9fywm4wqawy8udszd3l66hs9vktdtl73c0nqwl5hlk",
  • "funcName": "multiPairSwap",
  • "args": [
    ],
  • "value": "KFI=10"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}