To support the SPS Delegation Rental Market there will be a few new APIs.

When the changes go live API documentation will be available here: https://vapi.splinterlands.com/swagger/#/delegation-rental


# API summary:

**Bids:**

**https://vapi.splinterlands.com/delegation-rental/bids**: can be used to get all bids that have been submitted.
The results can be paged using `offset` and `limit` params and sorted using the `order` and `sort` params.
The results can be filtered to bids created by a certain player using the `player` param.
Finally, `status` can be used to filter on `open` (unfilled) bids, `complete` (filled) bids and `cancelled` bids.


Sample response:

{
  "status": "success",
  "data": [
    {
      "txId": "e6a82abe2c5d352bbc3956536d35323ed0fabb7f-8",
      "createdDate": "2023-06-29T15:31:36.000Z",
      "lastUpdatedDate": "2023-06-29T15:31:36.000Z",
      "lastUpdatedTx": "e6a82abe2c5d352bbc3956536d35323ed0fabb7f",
      "player": "lilyfire",
      "token": "SPSP",
      "qtyTotal": "100.000",
      "qtyAvailable": "100.000",
      "pricePerToken": "10.000",
      "escrow": "7000.000",
      "currency": "DEC",
      "cancelTx": null
    }
  ]
}

`txId` - hive block transaction id (https://hiveblocks.com/tx/e6a82abe2c5d352bbc3956536d35323ed0fabb7f) though note the `-8` suffix due to multiple bids being created from the same transaction
`player` - player who created the bid
`token` - token to be rented (currently only `SPSP` is supported)
`qtyTotal` - number of total tokens to be rented
`qtyAvailable` - number of tokens available to be rented (currently partial bid filling is not supported so this will either equal `qtyTotal` when not filled or `0` if filled)
`pricePerToken` - amount of currency per token per day that the rental will cost
`escrow` - amount of the below currency that gets put into escrow in order to satisfy the bid (`pricePerToken` * `qtyTotal` * 7 (delegation rentals are currently for 7 days))
`currency` - currency that was put into escrow. Either `DEC` or `CREDITS`
`cancelTx` - will be set with the hive block transaction id of the cancel operation if the bid was cancelled

**Filled bids/rentals:**

**https://vapi.splinterlands.com/delegation-rental/rentals/player/{player}** and **https://vapi.splinterlands.com/delegation-rental/rentals/bid/{bid}** both can be used to return filled bids and have a similar query and response structure.

**/player/{playerName}** gets all bids filled by a particular player

**/bid/{bidTxId}** gets all bids filled for a particular bid (using txId of the bid)
*NOTE: as of now this will be empty if the bid is unfilled and have only one item if the bid is filled. This is due to partial bid filling currently not being supported. If in the future partial bid filling is supported, then this will return all partial fillings of the bid.*

The results can be paged using `offset` and `limit` params and sorted using the `order` and `sort` params.


Sample response:

{
  "status": "success",
  "data": [
    {
      "txId": "dcab39e53a135897f65f065960c5d674c8008d1d",
      "bidTxId": "e6a82abe2c5d352bbc3956536d35323ed0fabb7f-8",
      "createdDate": "2023-07-03T22:50:48.000Z",
      "player": "antiosh",
      "qty": "100.000",
      "paymentAmount": "7000.000"
    }
  ]
}

`txId` - hive block transaction id of the bid filling transaction
`bidTxId` - transaction id of the bid being filled
`player` - player who filled the bid
`qty` - amount of tokens delegated when the bid was filled (currently will be the full requested `qtyTotal` amount as partial bid filling is not supported)
`paymentAmount` - amount of `DEC` received for filling the bid, before any market/burn fees are taken into account (will be full `escrow` amount of the bid)

# Blockchain Operations
To support the SPS Delegation Rental Market there will be three new blockchain operations. They will all require active authority. These operations will support rental authority, similar to the card rental market to allow third-party tools and services to manage SPS rentals for players without the need for players to share logins or keys.

**sm_rent_token**

Used to create a bid that indicates that a player is looking to rent a specified amount of tokens at a certain price.
When a bid is created the specificied currency gets put into an escrow account that will either be returned if the bid is cancelled or paid to the token owner when the bid is filled. The amount of `currency` that gets put into escrow in order to satisfy the bid is: `price * qty * 7` (7 as delegation rentals are currently for 7 days).

Sample JSON:

{ 
	"token": "SPSP",
	"qty": 10000,
	"currency": "DEC",
	"price": 1,
	"split": 1,
	"player": "magic-turtle"
}

`token` - The token that this player is looking to rent. Currently only supports `SPSP`
`qty` - The total quantity of the token that the player is looking to rent (minimum of 100 is required)
`currency` - The currency that the user wants to pay in (either `DEC` or `CREDITS`).
*NOTE: Players filling the bids will always be paid out in DEC as Splinterlands will take the CREDITS and pay out the DEC to the bid filler.*
`price` - The amount of `currency` per token per day that the renter is willing to pay
`split` - (optional - defaults to 1) indicates that the qty should be split into the specified number of separate bids (maximum of 10 allowed)
*Note: A suffix will be added to the txid for each bid created e.g. txid-1, txid-2, etc.*
`player` - (optional) if a user has granted rental authority to another account, this account will need to specify the `player` for who they are performing the action on behalf of
***IMPORTANT: Only use this if using rental authority on behalf of another player, if you are creating a bid for yourself, do not set this.***

**sm_cancel_rent_token**

Used to cancel a bid (or multiple bids) that you no longer want to be filled. The escrow payment will be returned.

Sample JSON:

{ 
	"bid_tx_ids": ["e6a82abe2c5d352bbc3956536d35323ed0fabb7f-8"],
	"player": "magic-turtle"
}

`bid_tx_ids` - an array of bid transaction ids to be cancelled
`player` - (optional) if a user has granted rental authority to another account, this account will need to specify the `player` for who they are performing the action on behalf of
***IMPORTANT: Only use this if using rental authority on behalf of another player, if you are cancelling a bid for yourself, do not set this.***

**sm_fill_token_rental**

Used to fill a bid. The player filling the bid will delegate the total quantity of the required token and receive the escrow payment (minus market and burn fees).

Sample JSON:

{ 
	"bid_tx_id": "e6a82abe2c5d352bbc3956536d35323ed0fabb7f-8",
	"player": "magic-turtle",
	"market": "splinterlands"
}

`bid_tx_id` - the bid to be filled
`player` - (optional) if a user has granted rental authority to another account, this account will need to specify the `player` for who they are performing the action on behalf of
***IMPORTANT: Only use this if using rental authority on behalf of another player, if you are filling a bid for yourself, do not set this.***
`market` - (optional) the market that was used to fill the bid which will receive the market fees. If not set or not a valid market account it will default to the Splinterlands market account.