lurkcoin-core/HTTPS API.md

# lurkcoinV3 API documentation

lurkcoin provides an API for servers and other integrations.

In version 3 of the API, JSON is recommended for requests and used for all
responses. If you cannot decode JSON, you should probably use the legacy
[lurkcoinV2 API](https://gist.github.com/luk3yx/8028cedb3bfb282d9ba3f2d1c7871231).
There are currently no plans to remove the older API.

All API endpoints require an `Authorization` header with the
[`Basic`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme)
authentication scheme. If the username somehow happens to contain colons (`:`),
these can be replaced with underscores (`_`).

*With Python's requests library, you can simply add
`auth=('username', 'token')` as a keyword argument.*

# Response format

All responses will be a JSON object containing a `success` boolean. If lurkcoin
encounters errors processing your request, this will be false and an error code
will be added to the response. Otherwise, the response data (if any) will be in
the `result` key.

The `X-Force-OK` header can be set to `true` to force a `200 OK` reply even
when an error occurs.

### Examples

```json
{
    "success": true,
    "result": 1234.56
}
```

```json
{
    "success": false,
    "error": "ERR_CANNOTAFFORD",
    "message": "You cannot afford to do that!"
}
```

### Globally raised errors

The following errors may be raised on any API endpoint:
 - `ERR_INVALIDLOGIN` when either `username` or `token` is invalid.
 - `ERR_INVALIDREQUEST` when required parameters are missing or are an invalid
    type.
 - `ERR_INTERNALERROR` when something really nasty happens.

# API endpoints

## GET `/v3/summary`

Returns an "account summary".

This endpoint returns a JSON-formatted object with the following items:
 - `uid`: An internal UID for the user, this is probably the username with
    only the following characters: `[A-Za-z0-9_]+`.
 - `name`: The username for the user. This is used in [transaction objects].
 - `bal`: A number with the user's current balance.
 - `balance`: The balance formatted as a string (if `bal` is `1.23`,
    `balance` will be `¤1.23` or similar).
 - `history`: A list with the 10 most recent [transaction objects].
 - `interest_rate`: The current interest rate.
 - `target_balance`: The server's target balance. This will be
    `0` if the server's local currency is equal to lurkcoin.

## POST `/v3/pay`

Sends a payment to a user. This will return the transaction object (see
`/v3/history`) on success. This can optionally be used to generate transaction
IDs for local transactions.

Parameters:
 - `source`: The user who is sending the transaction.
 - `target`: The target user to pay.
 - `target_server`: The server to pay the user on.
 - `amount`: The amount to pay the user.
 - `local_currency`: If `true`, lurkcoin will calculate the
    local server's exchange rate before processing the transaction.

Errors raised:
 - `ERR_SERVERNOTFOUND` when `target_server` doesn't exist.
 - `ERR_INVALIDAMOUNT` when the amount is invalid
 - `ERR_CANNOTPAYNOTHING` when the amount (after exchange rate calculations)
    is ¤0.00.
 - `ERR_CANNOTAFFORD` when your balance is lower than the amount sent (in
    lurkcoins).

## GET `/v3/balance`

Returns your account balance as a number.

## GET `/v3/history`

Returns a list of [transaction objects].

## POST `/v3/exchange_rates`

Gets the exchange rate for the specified server. Will return a number.

Parameters:
 - `source` *(optional)*: The server the money is hypothetically coming from.
 - `target` *(optional)*: The server the money is hypothetically going to.
 - `amount`: The amount of money being transferred.

Errors raised:
 - `ERR_SOURCESERVERNOTFOUND` when `source` doesn't exist.
 - `ERR_TARGETSERVERNOTFOUND` when `target` doesn't exist.
 - `ERR_INVALIDAMOUNT` when `amount` is invalid.

## GET `/v3/pending_transactions`

Returns a JSON-formatted list of unprocessed [transaction objects]. Note that
the order of this list is not guaranteed to be the same between API calls.

## POST `/v3/acknowledge_transactions`

Marks transactions as processed. Invalid or already processed transaction IDs
will be silently ignored.

**Please cache processed transaction IDs until this request has succeeded to
stop transactions being applied twice.**

Parameters:
 - `transactions`: A list of transaction IDs that have been processed.

## POST `/v3/reject_transactions`

Marks transactions as rejected, for example when one was sent to a non-existent
user. Invalid or already processed transaction IDs will be silently ignored.

*If a transaction gets marked as rejected, the target user (if any) must not
receive the transaction as the transaction may be reverted.*

Parameters:
 - `transactions`: A list of transaction IDs that have been rejected.

## GET `/v3/target_balance`

Gets the target balance. This will be `0` if the server's currency is equal to
lurkcoin.

## PUT `/v3/target_balance`

Sets the server's current balance.

Target balances are used with calculating exchange rates, if the server's
balance is lower than this target balance the currency will be less valuable
than lurkcoin.

**Please do not set ridiculously high/low target balances without a good reason
for doing so.** This API endpoint may have a maximum/minimum target balance
added in the future.

Set the target balance to `0` if the server's currency should have a 1:1
exchange rate with lurkcoin (or if the server's local currency *is* lurkcoin).

Parameters:
 - `target_balance`: The new target balance.

Errors raised:
 - `ERR_INVALIDAMOUNT`: Invalid target balance.

## GET `/v3/webhook_url`

Gets the server's webhook URL, or `null` if webhooks are not enabled. Every
time a transaction gets sent to the server a POST request will be sent to this
URL similar to the below example.

```
POST /lurkcoin HTTP/1.1
User-Agent: lurkcoin/3.0
Content-Length: 14
Content-Type: application/json

{"version": 0}
```

The request does not contain transaction information because there is currently
no reliable way to validate that the request has indeed originated from
lurkcoin.

# Alternate API endpoints

All `GET`-based endpoints also accept `POST`.

## POST `/v3/set_target_balance`

Equivalent to sending a PUT to `/v3/target_balance`. Can be used if you can't
or don't want to send `PUT` requests.

# Transaction objects

[transaction objects]: #transaction-objects

Transaction objects are defined as follows:

```js
{
    // The transaction ID
    "id": "T5E1816DE-9ACB0442",

    // The user who sent this transaction and the server they are on.
    "source": "sourceuser",
    "source_server": "sourceserver",

    // The user who has received this transaction and their server.
    "target": "targetuser",
    "target_server": "targetserver",

    // The amount sent in lurkcoins.
    "amount": 851.80,

    // The amount in the sending server's local currency.
    "sent_amount": 123.45,

    // The amount in the receiving server's local currency.
    "received_amount": 1650.52

    // The time the transaction was sent in seconds since the UNIX epoch.
    "time": 1578637022,

    // If this is false, the transaction will not be reverted if it gets
    // rejected by the receiving server.
    "revertable": true,
}
```

Extra items must be ignored by the client as these may be used in the future
to add more features.