Getting started

Introduction

Welcome to Spectral, the leading provider of on-chain risk insight! This developer documentation will touch on our available forms of delivery, our products, and how to get started today!

To gain access to any of our products, get in touch with us!

Version: 0.1.0

Spectral URLs

This is the base URL for making API requests to the Integration REST API for pulling data directly into your applications.

Integration REST API URL

https://api.spectral.finance

SDK

SDK Overview

The Spectral SDK provides a user-friendly, comprehensive, and consent-based solution to ease the integration into React applications. The SDK communicates with our API to retrieve information on risk insight.

DEMO PAGE

Prerequisites - Partner ID

Access to the SDK requires a Partner ID! With the SDK in beta, if you are interested in using this solution, get in touch with us!

SDK Installation

In order to install the SDK run

npm install @spectral-finance/spectral-modal

yarn add @spectral-finance/spectral-modal.

SpectralProvider import

import { SpectralProvider } from "@spectral-finance/spectral-modal";

export const App = () => {
  return (
    <SpectralProvider logo="yourLogoImageURL" partnerId="yourPartnerId">
      <RouterOrHome />
    </SpectralProvider>
  );
};

Import SpectralProvider and wrap it around the root app component. Use the logo parameter to apply a custom logo, and the partnerID parameter to verify your Partner ID.

Calculate MACRO score from within your application

import { SpectralProvider } from "@spectral-finance/";

export const Home = () => {
  const { start, score } = useSpectral();
  const [myScore, setMyScore] = useState();

  useEffect(() => {
    if (!score) {
      console.log("Score not calculated");
      return;
    }
    console.log(`Hooray! your score is ${score}`);
    setMyScore(score);
  }, [score]);

  return (
    <div>
      {/* Opens the Spectral Modal and start the bundle and
     calculation process */}
      <button type="button" onClick={start}>
        Calculate Spectral Score
      </button>
    </div>
  );
};

The useSpectral hook can be used anywhere inside the app context. Once the MACRO score is calculated it will be served within the score key provided by the hook.

Integration REST API

API Overview

The Integration REST API is a bridge for partners to pull risk insights directly into their application. The base URL for REST API can be found at Spectral URLs section.

Authentication

Sample HTTP Request

GET /api/v1/addresses/0x573d19B66Cdc33f7E751f2a478ECeCe95155e798
Host: https://api.spectral.finance
Authorization: Bearer SFMYYYY.g2kfhsjAACRjNjliZWIwZS1jYTc1LTRjODUtOWVlMy01YThiZmI0MTAxNTVuBgCAlkjahsdlkfAFiAAFRgA.iEtc7xPGEemU-Z63sDQSTNmVFzCogdPycG7sAUK7p9k...

All requests to the Integration REST API have to be authenticated with an API key (bearer access token). To obtain an API key get in touch with us!

Include the token in the HTTP Authorization header of your REST requests as a bearer token:

Authorization: Bearer <token>

Integration API Endpoints

Get MACRO Score

   curl -i -X GET \
   'https://api.spectral.finance/api/v1/addresses/{wallet_address}'

Sample response

   {
    "score": "350.00",
    "score_ingredients": {
      "credit_mix": 2,
      "defi_actions": 3,
      "health_and_risk": 4,
      "liquidation": 5,
      "market": 1,
      "time": 6,
      "wallet": 7
    },
    "score_timestamp": "2019-08-24T14:15:22Z",
    "wallet_address": "0xb4537b5bDfF24F757b939E27510b107BE2Ad473C"
   }

Description: Requests the pre-calculated MACRO score of a given wallet holder.

HTTP Request

GET /api/v1/addresses/{wallet_address}

Parameters

Name	Located in	Description	Required	Type
wallet_address	path	Wallet Address	Yes	`string`

Responses

Code	Description
200	Wallet Details

Calculate MACRO Score

   curl -i -X POST \
   'https://api.spectral.finance/api/v1/addresses/{wallet_address}/calculate_score'

Description: Initiates calculation of a wallet holder's score.

HTTP Request

POST /api/v1/addresses/{wallet_address}/calculate_score

Parameters

Name	Located in	Description	Required	Type
wallet_address	path	Wallet Address	Yes	`string`

Responses

Code	Description
200	MACRO score calculation has been successfully scheduled.

List Wallets

   curl -i -X GET \
   'https://api.spectral.finance/api/v1/addresses'

Sample response

   [{
      "score": "350.00",
      "score_ingredients": {
        "credit_mix": 2,
        "defi_actions": 3,
        "health_and_risk": 4,
        "liquidation": 5,
        "market": 1,
        "time": 6,
        "wallet": 7
      },
      "score_timestamp": "2019-08-24T14:15:22Z",
      "wallet_address": "0xb4537b5bDfF24F757b939E27510b107BE2Ad473C"
    },
    {
      "score": "740.00",
      "score_ingredients": {
        "credit_mix": 2,
        "defi_actions": 6,
        "health_and_risk": 4,
        "liquidation": 5,
        "market": 1,
        "time": 3,
        "wallet": 7
      },
      "score_timestamp": "2019-08-24T14:11:22Z",
      "wallet_address": "0xD7A556117f38c352a466F3DF33229a0ff8C4FC66"
   }]

Description: Requests information about all the wallets associated with the integration.

HTTP Request

GET /api/v1/addresses

Responses

Code	Description
200	Returns an array of Wallet Details

Get Wallet Insights

   curl -i -X GET \
   'https://api.spectral.finance/api/v1/addresses/{wallet_address}/insights'

Sample response

  {
    {
      "defi_transactions": {
        "borrow_events": {
          "borrow_total_borrows": 0,
          "borrow_sum_borrows": "string",
          "borrow_avg_borrows": "string",
          "borrow_total_area_eth": "string",
          "borrow_total_time_in_ever": 0,
          "borrow_total_current_loan_eth": "string",
          "borrow_total_interest_paid": "string"
        },
        "repay_events": {
          "borrow_total_repays": 0,
          "borrow_sum_repays": "string",
          "borrow_avg_repays": "string"
        },
        "deposit_lending": {
          "lending_total_deposits": 0,
          "lending_sum_deposits": "string",
          "lending_avg_deposits": "string",
          "lending_total_area_eth": "string",
          "lending_total_interest_earned": "string",
          "lending_total_time_in_ever": 0
        },
        "redemtions": {
          "lending_total_redeems": 0,
          "lending_sum_redeems": "string",
          "lending_avg_redeems": "string"
        },
        "liquidations": {
          "liquidation_total_liquidations": 0,
          "liquidation_total_amount_eth": "string",
          "liquidation_avg_amount_eth": "string",
          "liquidation_time_since_last_liquidated": 0
        }
      },
      "defi_risk_factors": {
        "borrow_current_risk_factor": "string",
        "borrow_avg_risk_factor": 0,
        "borrow_max_risk_factor": 0,
        "misc_total_collateral_eth": "string",
        "misc_avg_total_collateral_eth": "string",
        "borrow_weighted_avg_risk_factor": 0,
        "borrow_counts_above_threshold": 0,
        "misc_available_borrows_eth": "string",
        "misc_avg_available_borrows_eth": "string"
      },
      "wallet": {
        "wallet_total_current_balance_eth": "string",
        "wallet_first_tx": "string",
        "wallet_last_tx": "string",
        "wallet_age": 0,
        "wallet_total_incoming_tx": 0,
        "wallet_total_outgoing_tx": 0,
        "misc_total_fees_eth": "string",
        "misc_avg_total_fees_eth": "string",
        "wallet_current_balance_stablecoin_percentage": 0,
        "wallet_current_balance_topcoin_percentage": 0,
        "wallet_min_eth_ever": "string",
        "wallet_max_eth_ever": "string",
        "wallet_total_area_in_eth": "string"
      },
      "credit_mix": {
        "credit_mix_count": 0,
        "credit_mix_count_lending": 0,
        "credit_mix_count_borrow": 0,
        "credit_mix_max_lending_concentration": 0,
        "credit_mix_max_borrow_concentration": 0
      },
      "nfts": {
        "nft_total_nft_value": "string",
        "nft_total_auc_value": "string",
        "time_first_nft": "string"
      },
      "dexs": {
        "coming_soon": "string"
      },
      "rugpull": {
        "rug_pull_interaction_count": 0,
        "outgoing_value_count_rug_pulls": {
          "count": 0,
          "value": "string"
        },
        "first_last_timestamp_rug_pulls": {
          "first": "string",
          "last": "string"
        }
      }
    }
  }

Description: Requests the data packs of a given wallet holder.

HTTP Request

GET /api/v1/addresses/{wallet_address}/insights

Parameters

Name	Located in	Description	Required	Type
wallet_address	path	Wallet Address	Yes

Responses

Code	Description
200	Wallet Insights

Integration API Objects

Wallet Details

Attribute	Type	Format	Description
`score`	`string`	Number	MACRO score value.
`score_ingredients`	`object`	Score Ingredients	Additional ingredients of the MACRO score.
`score_timestamp`	`string`	Date Time	Timestamp at which the score has been calculated.
`wallet_address`	`string`	Ethereum wallet address

Wallet Insights

Attribute	Type	Format	Description
`credit_mix`	`object`		TBD
`defi_actions`	`object`		TBD

Score Ingredients

Attribute	Type	Description
`credit_mix`	`integer`	TBD
`defi_actions`	`integer`	TBD
`health_and_risk`	`integer`	TBD
`liquidation`	`integer`	TBD
`market`	`integer`	TBD
`time`	`integer`	TBD
`wallet`	`integer`	TBD