The Sheepy API provides merchants with access to crypto processing services and information.

We have two environments:

• Sandbox: This is only needed when testing out your integration with Sheepy.
• Production: In order to provide you with access to the production environment, we require that the integration is tested first. We just want to make sure that everything works the way it should.

Both environments are available via https://api.sheepy.com and are controlled by the switch in the top left corner of the dashboard. API access is regulated through the use of the X-Token authorization header value.

All API queries must be made over HTTPS, and plain HTTP will be refused.

API resources are available with a token, which must first be created on the API integration page. For each environment (Sandbox and Production), individual tokens are created and work only with that environment.

In the token settings, you can specify the permissions and the list of allowed IP addresses (if the list is empty, requests are accepted from any addresses).

The term "token" refers to a combination of api_key and secret_key, necessary for API authentication and authorization. Merchants can generate these keys through the Create New API Key section on the Sheepy Integration Page.

With each token, a secret key is generated, which is displayed only once at the time of token creation. Keep the secret key in a safe place because, in the future, it will not be possible to copy or edit it, only to generate a new one.

For each environment, you can create an unlimited number of tokens, which you can use and manage independently.

Requests to the Sheepy API follow a RESTful convention using standard HTTP verbs. The API responds with a JSON payload. When a data payload should be provided, it expects parameters to be passed in valid JSON.

Each request should include the following HTTP headers:

• Accept: application/json
• Content-Type: application/json

All requests must contain the following headers:

• X-Token - an API key that you generate on the API integration page.
• X-Signature - signature of the request (see below).
• X-Timestamp - the number of seconds since Unix Epoch in UTC.

The value of the X-Signature is generated by a SHA-256 HMAC algorithm using a secret key (provided upon API Token generation) on the bytes obtained by concatenating the following information:

• A timestamp (value of the X-Timestamp header) taken as a string.
• An HTTP method name in uppercase, e.g., GET or POST.
• URL of the request starting with (1) https://api.sheepy.com, (2) slash /, (3) all query parameters, e.g., https://api.sheepy.com/api/v1/invoices?requestTtl=1.
• Request body, taken exactly as it will be sent.

An example of generating a signature in PHP:

$timestamp = time();
$httpMethod = 'POST'; // or 'GET'
$url = 'https://api.sheepy.com/api/v1/invoices';
$body = json_encode(['amount' => 1000]);

$signature = hash_hmac('sha256', $timestamp . strtoupper($httpMethod) . $url . $body, $secretKey);

Additionally, you can specify the request lifetime using the optional query parameter requestTtl with a value from 5 to 60 seconds (the default value is 5 second).

There is a limit on the number of requests to API resources, which is set at 600 per minute per user. When this limit is reached, the response code for any further requests will be 429. Additionally, the Retry-After header will specify the number of seconds to wait before making another request.

A webhook is an HTTP POST request sent to a target you define in the notification URL on the Integration Profile page.

Please note that we do not send any info to endpoints using HTTP (HTTPS only).

Any notification is sent only once, regardless of the webhook endpoint response.

Change the status of an invoice:

{
    "type": "invoice_status_changed",
    "timestamp": 1674041910,
    "data": {
        "invoice": {
            ...
        }
    }
}

New deposit by deposit address:

{
    "type": "new_deposit",
    "timestamp": 1674041910,
    "data": {
        "address": {
            ...
        },
        "invoice": {
            ...
        }
    }
}

Change the status of a payout:

{
    "type": "payout_status_changed",
    "timestamp": 1674041910,
    "data": {
        "payout": {
            ...
        }
    }
}

The data in the atribute invoice, address, payout have the same format as in the requests for their retrieval:

• Retrieve invoice
• Retrieve deposit address
• Retrieve payout

It's better not to rely on our IP addresses for whitelisting them as webhook sender because they change from time to time.

To make sure that a webhook is sent by us, we have the option to sign it with the SHA-256 HMAC algorithm, similar to signing a request when accessing API resources (see the "Signing a request" section).

If you want to utilize this feature, you can reveal a Secret Key value on the Integration Profile page.

To verify that a webhook is sent by us:

1. Get the webhook X-Signature header value and payload as it is without any alteration or converting to JSON.
2. Receive the HTTP webhook body in bytes.
3. Perform calculations on your side to create a digest using Secret Key, raw webhook payload in bytes, and the SHA-256 HMAC algorithm.
4. Compare the X-Signature header value with the calculated digest.

This changelog presents a comprehensive record of all modifications and enhancements made to the Sheepy API, arranged in chronological order for easy tracking.

February 12, 2024

• Added invoices and payouts limits description
• The self_transfer attribute has been added to the Payout creation endpoint to indicate the ownership of the wallet address

December 11, 2023

• Added endpoint for simultaneous address and memo validation

November 27, 2023

• Added endpoints for payouts: Payout endpoints

October 23, 2023

• Added settings.service_fee_percent and settings.conversion_fee_percent to methods responses: List all invoices, Create a new invoice, Retrieve invoice

October 09, 2023

• Added settings.service_fee and settings.conversion_fee to method request: Create a new invoice

September 25, 2023

• Added the ability to retrieve balances: Retrieve wallet balances
• Added gate network fees output to list responses for the following method: Get gates
• Added deposit type to method request and responses, as well as deposit options to method responses: Deposit addresses
• Added the ability to get rates: Get rate

September 11, 2023

• Added invoice settings output to list responses for the following method: List all invoices, Create a new invoice, Retrieve invoice

August 1, 2023

• Added invoice configurations that override the default integration profile settings: Create a new invoice
• The parameters - currency, fees, notification_url, autocomplete, gates, and conversion - can now be overridden when creating an invoice

May 2, 2023

• Removed support for the deprecated gate_id parameter for gate identifiers. Now all methods only use the gate parameter with the gate name
• Removed support for the deprecated notification format

April 17, 2023

• Added the ability to specify a gate name when creating an invoice
• Added deposit addresses
• Updated notification format

April 3, 2023

• Added gate name output to method responses: Get gates, List all invoices, Retrieve invoice, Create payout
• The gate_id query parameter is declared deprecated, and the gate parameter should now be used instead

The current list of supported cryptocurrencies. Each gate has a unique name/ticker that does not change over time.

Production gates

Sandbox gates

Here is the current list of gates equipped with conversion capability. You can configure the conversion settings on the Integration Profile page.

Production gates conversion table

Sandbox gates conversion table

The list of available Sheepy merchant balances.

This section provides details on the available Sheepy merchant balances. Each gateway maintains its balance separately. Merchants can transfer funds from one gateway to another by using the manual conversion feature.

There are two primary methods to increase your balance:

• Invoice payments by your clients: You can create invoices for your clients using the API method Create a new invoice.
• Deposits to your deposit address by you or your clients: generate a new deposit address with the API method Create a new deposit address.

Debits from your balance occur when initiating withdrawals, payouts, mass payouts, and refunds.

An invoice is a form used by customers to make payments to Sheepy merchants. Merchants create invoices via a request to Sheepy API. Invoice request generates a secure Sheepy-hosted page where customers can view the items, amounts, fees, rates and other invoice details.

The invoice is valid for 15 minutes starting from the invoice creation, when time runs out and the invoice becomes invalid. Invoice status changes are accompanied by notifications being sent to the merchant's URL specified in the integration profile settings. Notifications about invoice statuses can also be sent to customers if the merchant specifies their email addresses when creating invoices.

Invoice amount excluding fees should not be less than 1 Euro and more than 15000 Euro.

* Final statuses

You have the option to create a deposit address and subsequently provide it to your clients (type customer_deposit). It is not necessary to create new invoices for each deposit address.

Upon receipt of payment to the designated deposit address, our system will generate an invoice and issue a corresponding notification to you. The invoice will be marked as "done" immediately, and the amount paid (minus fees) will be credited to your wallet. If you have configured conversion in your profile, it will be applied accordingly.

It is required to assign a unique text label to the customer's deposit address, such as a user_id in your system. This text label will be incorporated into notifications for paid invoices.

You can also create a deposit address for self-funding your account in both cryptocurrency and fiat currency (type merchant_deposit). Only one such account can be created for each gateway.

The "Mass Payouts" feature in our API facilitates the execution of bulk cryptocurrency transactions. To leverage this, validate your addresses using the Validate address and memo endpoint to ensure accuracy. Utilize the Create payout endpoint to initiate each payout, observing the specific Limits and Quotas as well as individual gate payout limits. Each payout is processed independently, offering status notifications for tracking.

For reviewing previously executed payouts, the List of payouts endpoint can be used with relevant query parameters. Additionally, mass payouts can be managed through the Payouts section of your personal dashboard, where all transactions are logged in the History page.

The payout method allows the merchant to make a cryptocurrency outgoing transaction in cryptocurrency. It is suitable for both one-time and regular transactions. To create a payout, the merchant must have an available balance equal to or bigger than the payout amount, including applicable fees. Also, payout amount excluding applicable fees should be in accordance with the "Payout limits" in gates table.

* Final statuses

This method allows the merchant to retrieve real-time fiat to cryptocurrency exchange rates. This feature is essential for accurately setting prices or conducting transactions in multiple cryptocurrencies. The rates are updated dynamically to reflect current market conditions.

The Sheepy’s onramp service streamlines the direct purchase of cryptocurrencies using credit cards. The purchased funds are deposited directly into the merchant's wallet, integrating seamlessly into a single payment flow (refer to the deposit addresses feature mentioned previously). The API methods outlined below facilitate the redirection of customers to the cryptocurrency purchase interface, with pre-filled parameters such as amount and currencies. Successful deposits can be tracked on the dashboard under the History page.