cryptoarena v1.0.8

Cryptoarena devtool

Cryptoarena devtool is a a cross-platform command line interface for managing developer apps and accounts.

All CLI commands are also available as an HTTP API

HTTP API

• API calls should be directed to https://cwst.cryptoarena.us
• All non-dev calls should include cookies setted by Set-Cookie headers (same cookie behaviour as browsers)
• All non-login endpoints return a JSON object in the following form:

type ApiResult = {
    status: "Success",
    data: any
} | {
    status: "Error",
    errorMessage: string
}

login

Gets an access token

The access token is required for all CLI commands and expires in 1 day

The login command is splitted in two endpoints, the first one gets a temporary token used to verify the user OTP or 2FA, the second takes the 2FA code and returns the access tokens.

These are the only endpoints that return a Set-Cookie header.

POST `/api/AuthenticateUser`

type RequestBody = {
    email: "your@email",
    password: "your_password",
    secure: true
}

type Response =  {
    // Token expiration date in ISO-8601
    tokenExpiry: string;
    twoFAMehtod: "GAuth" | "Email";
}

// Response includes Set-Cookie headers with temporary token

//*******************************************************************

POST `/token`
// Request SHOULD include cookies from previous /api/AuthenticateUser call

// Note that /token endpoint needs a URLSearchParams formatted body
type RequestBodyURLSearchParams = {
    grant_type: "password",
    // OTP either from user email or Google 2FA
    password: string, 
    secure: "true"
}

type Response =  {
    token_type: "bearer";
    /**UNIX seconds expiration date */
    expires_in: number;
}

// Response includes Set-Cookie headers with access tokens
// Now you can use any other endpoint

init

Upgrades your account to a developer account, enabling you to create apps and send payment requests

POST `/api/v2/Dev/Init`

type RequestBody = {
    // Globally unique developer name
    Name: string,
}

type Response =  {
    status: "Success"
}

createApp

Creates a new application that can hold a collection of API keys and send payment requests to users. Initially no API keys are created, use the addApiKey endpoint to create keys.

POST `/api/v2/Dev/Init`

type RequestBody = {
    // Internal name used as identifier, unique per developer
    // Should start with a letter and contain only letters, numbers and underscores
    DevName: string,

    // Name shown to end users, globally unique
    FriendlyName: string,
}

type Response =  {
    status: "Success"
}

listApps

Returns all developer apps

GET `/api/v2/Dev/ListApps`

type Response =  {
    data: {
        DevName: string,
        FriendlyName: string
    }[],
    status: "Success"
}

listApiKeys

Returns a list of API keys for an app

GET `/api/v2/Dev/ListApiKeys?AppDevName=${your_app_dev_name}`

type Response =  {
    data: {
        // Your API key
        Key: string,
        Enabled: boolean
    }[],
    status: "Success"
}

addApiKey

Adds an enabled API key to an app, returns the newly added key and an unrecoverable password that you need to store securely. If you loose the password the API key will be unusable and you'll need to add another one.

POST `/api/v2/Dev/SwitchApiKey`
type RequestBody = {
    // App developer name
    DevName: string
}

type Response =  {
    data: {
        // The new API key
        Key: string,
        // Unrecoverable password that you need to store
        Password: string
    },
    status: "Success"
}

switchApiKey

Change enable/disable state of an API key

POST `/api/v2/Dev/SwitchApiKey`
type RequestBody = {
    Key: string,
    Enabled: boolean
}

type Response =  {
    status: "Success"
}

sendInvite

Sends an app invitation to a user. For security reasons we don't report if the user exists. If the invitation was already sent, an error is returned with the InviteId enclosed in single quotes

POST `api/v2/Dev/SendInvite`

type RequestBody = {
    // An enabled API key that identifies the app
    ApiKey: string,

    // A client side generated GUID 
    InviteId: string,
    UserEmail: string
}

type Response =  {
    // The status is success even if the user doesn't exists
    status: "Success"
}

Example:

host='https://cwst.cryptoarena.us'
apiKey='my_app-prod-0gWTenjrSj84ft44WWTH2vsl7KjXrwljRQBBydlyGeQ'
userEmail='r.salguero@garsalabs.com'
inviteId=$(uuidgen)

curl "$host/api/v2/Dev/SendInvite" \
-X POST \
-H "Content-Type: application/json" \
-d '{"ApiKey": "'$apiKey'", "InviteId": "'$inviteId'", "UserEmail": "'$userEmail'"}'

getUserKey

Returns the user identifier only if the given invite is accepted, if not accepted or if the user doesn't exists, returns an error status

GET `api/v2/Dev/GetUserKey?ApiKey=${your_api_key}&InviteId=${your_invite_id}`

type Response =  {
    // User key
    data: string,
    status: "Success" 
}

Example:

curl "$host/api/v2/Dev/GetUserKey?ApiKey=$apiKey&InviteId=$inviteId"

sendPaymentRequest

Sends a payment request to a user that has already approved the app invite.

The developer can retry payments by sending payments with the same DevId. Never retry payments for the same concept with different ids, since this can result in multiple charges to the user.

POST `/api/v2/Dev/SendPaymentRequest`
type RequestBody = {
    // Payment id, a developer generated GUID 
    DevId: string,
    ApiKey: string,
    // Result from 'getUserKey'
    UserKey: string,
    Coin: string,
    Amount: string,
    // User friendly description, will be shown in the payment request notification
    Description: string,
}

type Response =  {
    // User key
    data: string,
    // The status is success even if the user doesn't exists
    status: "Success"
}

Example:

paymentId=$(uuidgen)
coin=USDT
amount=30
description="Gold skin"

curl "$host/api/v2/Dev/SendPaymentRequest" \
-X POST \
-H "Content-Type: application/json" \
-d '{"DevId": "'$paymentId'", "ApiKey": "'$apiKey'", "UserKey": "'$userKey'", "Coin": "'$coin'", "Amount": "'$amount'", "Description": "'$description'"}'

verifyPaymentRequest

Returns the status of a payment:

• Pending Waiting for user input or timeout.
• Approved The deposit is confirmed in dev account, the dev can now release any user purchase.
• Rejected The user manually rejected the payment or the payment timeout has been reached.

The user has 5 minutes to approve a payment and 15 minutes to confirm it. Thus, the max finality time is 20 minutes

There will never be a Pending payment with more than 20 minutes.

GET `api/v2/Dev/VerifyPaymentRequest?ApiKey=${your_api_key}&PaymentId=${your_payment_id}`

type Response =  {
    // User key
    data: {
        Status: "Pending"
    } | {
        Status: "Rejected",
        // Reject reason for debugging purposes only, do not show this message to the user
        Reason: string
    } | {
        Status: "Approved",
        // TxnHash for the confirmed deposit in dev account
        Confirmation: string
    },
    // The status is success even if the user doesn't exists
    status: "Success"
}

Example:

curl "$host/api/v2/Dev/VerifyPaymentRequest?ApiKey=$apiKey&PaymentId=$paymentId"

sendWithdrawal

Makes a withdrawal from your account to a user account, this withdrawal method skips email and 2FA confirmation, instead, relies on API password.

type RequestBody = {
    // Dev provided unique GUID, can be used as a nonce for retrying without the risk of double spending
    DevId: string;
    // Your API key
    ApiKey: string;
    // Your API secret password
    ApiSecret: string;
    // The user key of the withdrawal beneficiary
    UserKey: string;
    // Coin to send
    Coin: string;
    // Amount to send
    Amount: number;
    // Short user facing description
    Description: string;
}

type Response =  {
    // User key
    data: string,
    // The status is success even if the user doesn't exists
    status: "Success"
}

Example:

withdrawalId=$(uuidgen)
coin=XRP
amount=20

curl "$host/api/v2/Dev/SendWithdrawal" \
-X POST \
-H "Content-Type: application/json" \
-d '{"DevId": "'$withdrawalId'", "ApiKey": "'$apiKey'", "ApiSecret": "'$apiSecret'", "UserKey": "'$userKey'", "Coin": "'$coin'", "Amount": "'$amount'", "Description": "'$description'"}' \

verifyWithdrawal

Returns a confirmation ID if the withdrawal was successfully deposited to the user or null if the withdrawal wasn't executed

Example:

curl "$host/api/v2/Dev/VerifyWithdrawal?ApiKey=$apiKey&WithdrawalId=$withdrawalId"