2.7 Request invite and free Tokens from a Faucet

To buy a mebership first of all you have to be invited.

To do anything on a blockchain you need tokens. If you are operating on mainnet.commercio.network you need to purchase them from someone, since they are real money.

If you are operating on testnet.commercio.network you can have them for free, since they are like play money. We have an API service called Faucet.commercio.network that provides invitations and Commecio tokens for free to developers like you.

• Free of charge
• no string attached
• No biggie... they are just Monopoly™ money

Use cases

• Being invited.
• Recharge an account with free tokens.

Tools

Faucet, software that exposes some APIs on the Web.

Functions and APIs

/invite

• Method: GET
• Parameters:
  • addr: destination address
• Return value:
  • 200 if request is successful, along with a "/give response" JSON response
  • 403 if the request wasn't successful because of user error, along with an "Error" response
  • 500 if the request wasn't successful because of server error, along with an "Error" response

/give

• Method: GET
• Parameters:
  • addr: destination address
  • amount: amount of tokens to be sent from Faucet to addr, expressed in ucommercio
• Return value:
  • 200 if request is successful, along with a "/give response" JSON response
  • 403 if the request wasn't successful because of user error, along with an "Error" response
  • 500 if the request wasn't successful because of server error, along with an "Error" response

Step by step sequence

1. Call the invite API using the query parameter.
2. Get an hash if the transaction was succesfull.
3. Call the give API using all the query parameters; 100.000.000 ucommercio is the max amount available.
4. Get an hash if the transaction was succesfull.

Code Examples

Here's an example of the implementation in all the available languages.

Dart

const String authority = 'faucet-testnet.commercio.network';
const String address = 'did:com:1crltcqwt9r0tpy9v0jnuu7lw6snl5k2wez8cca';

const String pathInvite = '/invite';
final queryInvite = {
  'addr': address,
};
try {
  final response =
      await http.get(Uri.https(
        authority, pathInvite, queryInvite),
      );
} catch (error) {
  throw error;
}

const String pathGive = '/give';
final queryGive = {
  'addr': address,
  'amount': '100000000',
};
try {
  final response =
      await http.get(Uri.https(
        authority, pathGive, queryGive),
      );
} catch (error) {
  throw error;
}

Kotlin

// need implementation 'io.github.rybalkinsd:kohttp:0.10.0'

val authority = "faucet-testnet.commercio.network"
val address = "did:com:1crltcqwt9r0tpy9v0jnuu7lw6snl5k2wez8cca"

val pathInvite = "/invite"
try {
    val response = httpGet {
        url("https://$authority$pathInvite")
        param {
            "addr" to address
        }
    }
    print("\nResponse Invite: $response\n")
} catch (e: Error) {
        throw e
}


val pathGive = "/give"

try {
    val response = httpGet {
        url("https://$authority$pathGive")
        param {
            "addr" to address
            "amount" to "100000000"
        }
    }
    print("\nResponse free tokens: $response\n")
} catch (e: Error) {
    throw e
}