# Introduction Welcome to the API documentation for the Starfall Platform. ## What is Starfall? Starfall is a fraud and bot detection platform for every web3 wallet. We detect fraudulent behavior, suspicious actors, scams, and bots across 8 blockchains. With Starfall, you can search any wallet address and instantly get a fraud and bot score for that wallet, and a list of wallets related to that wallet based on a variety of on and off chain signals. #### Can I search my own wallet on Starfall? Yes, you can search your own wallet on Starfall to monitor for fraudulent transaction and potential bot activity. #### Can I integrate with Starfall? We provide a set of APIs to enable seamless integration with all of your applications. All of our predictions are available through our APIs. Here are some of our customer's use cases: * Prescreen wallets before they sign up for your platform * Go through all your customers wallets to determine if any of them belong to fraud or bot rings * Filter out bot wallets for air drops and give aways * Triage customer wallets from Starfall for potentially suspicious activity * Find related wallets for marketing and customer targeting As a wallet holder, you can use Starfall to: * Proactively monitor and check the fraud score of your own wallet * Take actions to improve your wallet's fraud and bot score * Screen wallets before you interact with them ## How do I get started? Go to our [quickstart tutorial](/quick-start). * Sign up for an account, get an API key through our [developer portal](https://app.starfall.ai) * From the free account, start looking up wallets. ## How do I get help? Contact the Starfall support team at with any questions. * Ask us directly in our [telegram channel](https://t.me/starfallpublic). # Quick Start Making your first request with Starfall ## Getting started The first step to starting with Starfall API is to create an acocunt and get an API key. * Create an account at . * Be sure to verify your email. Lookups are only allowed for verified emails. * Go to the [API tokens](https://app.starfall.ai/dashboard/api-tokens) page to copy your API token. ## Making a request Our entire API library is available at our [API reference](/api-reference) page. * Include your header `Authorization: Token ` in every API request. Here is the curl of a sample API request to lookup a new wallet address: ```powershell curl --location 'https://api.starfall.ai/api/addresses/0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97/' \ --header 'Authorization: Token ' ``` # API Usage Helpful info about the API ## Limits Currently, Starfall is offering our platform for free for the first 50 wallets lookups to every verified user. We are committed to extending our platform for free up to a limited amount of requests (subject to change) to every business through Q2 2024. If you business has a need for more free requests, please feel free to reach out to us at ## Rate limiting Starfall rate limits users in the free tier and this can be increased for business users. Please reach out to the Starfall team at if you'd like to integrate at a higher rate limit. ## Subscriptions We are currently working on a subscription model for our business users. As mentioned above we are committed to offering the platform for free through Q2 2024. Reach out to us for more information. ## Model versioning Starfall uses custom machine learning models to make predictions about every wallet using on and off chain data. Currently, all of our models run on the latest version of our data as of November 2023. We plan to include headers that specify the model version being used in our API through a `X-Model-Version` header and by passing this variable through a query parameter in the request. # API reference Documentation for the Starfall API The Starfall API is primarily divided into the following categories: Login using username and password to obtain a token. {% content-ref url="/spaces/Jkdbbg7vsOssgsTBMtsY/pages/fs5vx7xMGv66Im6hebm8" %} [Auth token](/api-reference/auth-token) {% endcontent-ref %} List of all of previously looked up addresses from your account and the number of address lookups already used. {% content-ref url="/spaces/Jkdbbg7vsOssgsTBMtsY/pages/Zutpn9C90vNmKM8mZDgU" %} [Address Lookups](/api-reference/address-lookups) {% endcontent-ref %} Search a new address and search accounts related to that address. {% content-ref url="/spaces/Jkdbbg7vsOssgsTBMtsY/pages/Jj4kx6nQBkBarkUGXIlV" %} [Addresses](/api-reference/addresses) {% endcontent-ref %} Get existing predictions and signals for a particular address. {% content-ref url="/spaces/Jkdbbg7vsOssgsTBMtsY/pages/Op02L6IDcAE4JybcD6Cu" %} [Final predictions](/api-reference/final-predictions) {% endcontent-ref %} Manage api tokens. {% content-ref url="/spaces/Jkdbbg7vsOssgsTBMtsY/pages/ik7ui6dKP9sjtjYB5x5v" %} [Broken mention](broken://spaces/Jkdbbg7vsOssgsTBMtsY/pages/ik7ui6dKP9sjtjYB5x5v) {% endcontent-ref %} Manage your user profie. {% content-ref url="/spaces/Jkdbbg7vsOssgsTBMtsY/pages/z7RO2BOzBSTvTrPyUqXa" %} [Users](/api-reference/users) {% endcontent-ref %} # Auth token Login using username and password to obtain a token. ## Get auth token for a user using username and password `POST` `https://api.starfall.ai/auth-token` #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ----------- | | username\* | String | username | | password\* | String | password | {% tabs %} {% tab title="200: OK Success" %} ```json { "token": "string" } ``` {% endtab %} {% endtabs %} # Addresses Look up addresses, get wallet information, find related wallets. Requires `Authorization: Token ` in the header. ## Lookup a wallet address using a hash and blockchain name and get predictions `GET` `https://api.starfall.ai/api/addresses/{hash}/?blockchain_name={blockchain_name}` #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | -------------- | | hash\* | String | Wallet address | #### Query Parameters | Name | Type | Description | | -------------------------------------------------- | ------ | ----------------------------------------- | | blockchain\_name\* | String | Name of the blockchain from i.e. ethereum | {% tabs %} {% tab title="200: OK " %} ```json { "id": 0, "name": "string", "hash": "string", "is_blacklist": true, "blockchain_name": "string", "final_predictions": [ { "id": 0, "predictions": [ { "id": 0, "created": "2023-11-30T10:55:57.374Z", "modified": "2023-11-30T10:55:57.374Z", "model_version": "string", "model_name": "string", "fraud_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "bot_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "run_number": 2147483647, "address": 0 } ], "created": "2023-11-30T10:55:57.374Z", "modified": "2023-11-30T10:55:57.374Z", "model_chosen": "string", "run_number": 2147483647, "fraud_probability": 0, "final_prediction": 2147483647, "fraud_message": "string", "has_erc20_token_transfers": true, "num_erc20_token_transfers": 2147483647, "has_transactions": true, "num_transactions": 2147483647, "is_bot": true, "address": 0 } ] } ``` {% endtab %} {% endtabs %} ## Get a list of related wallets to the wallet based on signals and predictions `GET` `https://api.starfall.ai/api/addresses/{hash}/related/?blockchain_name={blockchain_name}` Gives a list of related wallets to the current wallet. Clusters wallets based on predictions and signals and returns the closest cluster of wallets. #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | -------------- | | hash\* | String | Wallet Address | #### Query Parameters | Name | Type | Description | | -------------------------------------------------- | ------ | ----------------------------------------- | | blockchain\_name\* | String | Name of the blockchain from i.e. ethereum | {% tabs %} {% tab title="200: OK " %} ```json { "id": 0, "name": "string", "hash": "string", "is_blacklist": true, "blockchain_name": "string", "final_predictions": [ { "id": 0, "predictions": [ { "id": 0, "created": "2023-11-30T11:02:18.337Z", "modified": "2023-11-30T11:02:18.337Z", "model_version": "string", "model_name": "string", "fraud_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "bot_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "run_number": 2147483647, "address": 0 } ], "created": "2023-11-30T11:02:18.337Z", "modified": "2023-11-30T11:02:18.337Z", "model_chosen": "string", "run_number": 2147483647, "fraud_probability": 0, "final_prediction": 2147483647, "fraud_message": "string", "has_erc20_token_transfers": true, "num_erc20_token_transfers": 2147483647, "has_transactions": true, "num_transactions": 2147483647, "is_bot": true, "address": 0 } ] } ``` {% endtab %} {% endtabs %} # Final predictions Get final predictions for a single address Requires `Authorization: Token ` in the header. ## Get final predictions for a single address `GET` `https://api/starfall/.ai/api/final_predictions/{adress_hash}/` Retrieve final predictions for an address if one exists, this does not cause a lookup. #### Path Parameters | Name | Type | Description | | ----------------------------------------------- | ------ | -------------- | | address\_hash\* | String | Wallet address | {% tabs %} {% tab title="200: OK " %} ```json { "id": 0, "predictions": [ { "id": 0, "created": "2023-11-30T11:07:56.215Z", "modified": "2023-11-30T11:07:56.215Z", "model_version": "string", "model_name": "string", "fraud_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "bot_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "run_number": 2147483647, "address": 0 } ], "created": "2023-11-30T11:07:56.215Z", "modified": "2023-11-30T11:07:56.215Z", "model_chosen": "string", "run_number": 2147483647, "fraud_probability": 0, "final_prediction": 2147483647, "fraud_message": "string", "has_erc20_token_transfers": true, "num_erc20_token_transfers": 2147483647, "has_transactions": true, "num_transactions": 2147483647, "is_bot": true, "address": 0 } ``` {% endtab %} {% endtabs %} # Address Lookups Gives information about wallet address lookups executed by current user. Requires `Authorization: Token ` in the header. ## Get all address lookups done by the user `GET` `https://api.starfall.ai/api/address_lookups/` Gives a list of all address lookups executed by the current user {% tabs %} {% tab title="200: OK " %} ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": 0, "address": { "id": 0, "name": "string", "hash": "string", "is_blacklist": true, "blockchain_name": "string", "final_predictions": [ { "id": 0, "predictions": [ { "id": 0, "created": "2023-11-30T11:09:46.167Z", "modified": "2023-11-30T11:09:46.167Z", "model_version": "string", "model_name": "string", "fraud_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "bot_data": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "run_number": 2147483647, "address": 0 } ], "created": "2023-11-30T11:09:46.167Z", "modified": "2023-11-30T11:09:46.167Z", "model_chosen": "string", "run_number": 2147483647, "fraud_probability": 0, "final_prediction": 2147483647, "fraud_message": "string", "has_erc20_token_transfers": true, "num_erc20_token_transfers": 2147483647, "has_transactions": true, "num_transactions": 2147483647, "is_bot": true, "address": 0 } ] }, "created": "2023-11-30T11:09:46.167Z", "modified": "2023-11-30T11:09:46.167Z", "last_viewed": "2023-11-30T11:09:46.167Z", "user": 0 } ] } ``` {% endtab %} {% endtabs %} ## Counts all lookups used `GET` `https://api.starfall.ai/api/address_lookups/used/` Get a count of all lookups used by current user {% tabs %} {% tab title="200: OK " %} ```json { lookups_used: 100 } ``` {% endtab %} {% endtabs %} # Users Get information about current user and their subscription Use this endpoint to get information about the current user and their subscription status. This endpoint can always be called to update the user. Requires `Authorization: Token ` in the header. ## Get information about current user `GET` `https://api.starfall.ai/api/users/me/` Provides information about the current user and their subscription. {% tabs %} {% tab title="200: OK " %} ```json { "username": "wG1RyvhN2l3ve@qQ-4Fe4.Wrr3MlH9alk8sanaT86aXGIki3Rr8-8k9", "name": "string", "url": "string", "email": "user@example.com", "date_joined": "2023-11-30T11:16:39.971Z", "last_login": "2023-11-30T11:16:39.971Z", "subscription": { "id": 0, "subscription_plan": { "id": 0, "created": "2023-11-30T11:16:39.971Z", "modified": "2023-11-30T11:16:39.971Z", "name": "string", "description": "string", "price": 9999999, "duration": 9999999, "max_addresses": 9999999, "key": "string", "is_active": true }, "created": "2023-11-30T11:16:39.971Z", "modified": "2023-11-30T11:16:39.971Z", "start_date": "2023-11-30T11:16:39.971Z", "end_date": "2023-11-30T11:16:39.971Z", "user": 0 }, "email_addresses": [ { "id": 0, "email": "user@example.com", "verified": true, "primary": true, "user": 0 } ] } ``` {% endtab %} {% endtabs %}