# Socios.com Connect

Welcome to the Socios.com Connect Documentation site!

{% hint style="warning" %}
**2024-12-09 - ANNOUNCEMENT FOR SOCIOS.COM API DEVELOPERS**

In Q1 2025, the Chiliz team will decommission several endpoints and features from the Socios.com API. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem. 

Don't worry! We provide you with alternatives right here on this documentation site.
{% endhint %}

## Experience the Power of Fan Tokens on Your Platforms 

At the heart of our ecosystem is the belief that Fan Tokens reveal their full value when used beyond just Socios.com.\
\
Unlock a new dimension for your platform with our toolset designed to create Web3 experiences, right from your existing Web2 infrastructure. \
Our suite of tools makes integrating Fan Tokens an accessible feature for all sports fans -- and you can enrich your platform with unique Fan Token experiences, amplifying user engagement and driving the value of interaction. 

## Seamless Integration, Endless Possibilities 

Our toolkit is built on standard REST API and OAuth2 protocols, making integration as seamless as possible, even if you're not experienced with blockchain development. 

Take advantage of all Socios.com fan engagement tools directly on your platform and provide your users with fan token experiences from more than 155 sports clubs worldwide.

## Connection tools

* **Socios.com API**\
  Create personalized and engaging fan experiences, right in your own space, with your design and your existing flows.
* **Partner web app**\
  Every club partner can embed their dedicated Socios.com web kit within their website or mobile app in order to provide all Socios.com features and fan engagement tools to their fans.
* **Token sale (on-ramp fan token)**\
  Sell Fan Tokens directly from your digital platform.

{% hint style="info" %}
You can contact us at any time through our online forms:

* [Ask a question](https://mediarex.atlassian.net/servicedesk/customer/portal/5/group/12/create/55)
* [Report an incident](https://mediarex.atlassian.net/servicedesk/customer/portal/5/group/12/create/54)

*Note: You need to first create an account on the* [*Chiliz Help Center*](https://mediarex.atlassian.net/servicedesk/customer/portals)*.*
{% endhint %}


# DRAFT Stake & Earn guide

## Staking Fan Tokens

By staking your Fan Tokens, you can earn Reward Points on a daily basis, and possibly get quick access to great Socios.com rewards and activities!

### What is "Stake & Earn"

When browsing your assets in your Socios.com Wallet (the homepage of the Socios.com app), you can see a "Stake & Earn" button attached to each team for which you have obtained a Fan Token.

<figure><img src="/files/10oZzyn81XXzsgwqFpcT" alt=""><figcaption></figcaption></figure>

You can stake some of your Fan Token (or all of them) for any team.&#x20;

Each staked Fan Token will join an existing pool of rewards points, made of all the Fan Tokens staked by all Socios.com users.\
The pool then works for all users, and the more Fan Tokens you have staked, the more reward points you can obtain in return.

### How to stake your Fan Tokens

{% hint style="warning" %}
For now, you can only stake whole numbers for Fan Token, no decimals are allowed.
{% endhint %}

By clicking the "Stake & Earn" button attached to a give team, you are asking to stake some of your Fan Tokens for this team.

1. Choose the team/partner whose Fan Tokens you want to stake. Click the Stake & Earn button.
2. The staking interface opens, at first hidden behind a reminder modal window. Read it then close it.
3. The staking interface displays key information:
   * How many FTs you have for this team/partner.
   * How many FTs you want to stake. Click to edit the field.
   * How much reward points you could earn ***daily*** for the number of staked FTs you indicated
   * Information the reward pool for this team/partner.
4. Click the "Stake" button to start the staking process.&#x20;
5. The "Review" interface appears. We strongly advise you to pay attention to its information:
   * Stake: The amount of FT you want to stake.
   * Estimated earning: A reminder of you possible daily earnings in reward points.
   * Est. Network Fee: An estimation of how much CHZ the FT staking will cost you. \
     Indeed, because staking is a blockchain transaction, it comes with a small cost. That cost is taken from the amount of CHZ that you have on your Socios.com Wallet.&#x20;
   * Smart Contract: You can check the smart contract to which your FTs are sent to, thanks to blockchain transparency.
6. Click the "Confirm" button. For security reasons, Socios.com will ask for your Socios.com passkey, which you must have stored, either on your current device or your phone.

And voilà!

<figure><img src="/files/7z8mnVXZ29br3CDoxZbw" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
If you don't have enough CHZ on your Socios.com Wallet right now, you will not be able to stake.&#x20;

If that happens, you need to either:

* Buy more CHZ ("Top-up" button on the homepage).
* Send some CHZ to the Socios.com Wallet if you have CHZ in another wallet ("Receive" button on the homepage).

Once you have more CHZ on your Socios.com Wallet, you can start staking again.
{% endhint %}

### How to unstake your Fan Tokens

You can unstake your Fan Tokens anytime you want.

{% hint style="info" %}
As in most blockchains, Chiliz Chain has a "cool down" period for staking.&#x20;

You must wait 7 days between the moment when you ***unstake*** Fan Tokens, and the moment when you can ***claim*** these unstaked Fan Tokens — meaning, it takes 7 days before you can use them again for other Socios.com activities.

During those 7 days, your unstaked Fan Tokens are "locked": you cannot yet use them, and they don't earn any new reward points.
{% endhint %}

To unstake some Fan Tokens, follow these steps:

1. From the Socios.com app's "My Assets" section, click on the team whose Fan Tokens you have staked and want to unstake.
2. In that team's page, scroll down to the "Staked" section.
3. Click the "Click to unstake" link.
4. In the interface that opens, indicate how many FTs you want to unstake, then click the "Unstake" button.
5. Verify the information from the "Review" screen, and click "Confirm". Make sure you have enough CHZ for the transaction!
6. Click the "Confirm" button. For security reasons, Socios.com will ask for your Socios.com passkey, which you must have stored, either on your current device or your phone.

You're done!

## Staking CHZ

{% hint style="info" %}
This feature is currently being developped. For now, if you want to stake your CHZ, the remmended way is to use the [Chiliz Chain Governance site](https://governance.chilizchain.com/staking).

See the [Staking documention for Chiliz Chain](https://docs.chiliz.com/learn/about-staking) for complete details.
{% endhint %}


# Overview

This guide provides instructions on how to interact with the Chiliz Chain to perform various common tasks such as retrieving token balances (both ERC-20 and native tokens like CHZ), sending tokens, fetching transaction details, and more.

Through these pages, you will be equipped with the essential knowledge, and code snippets, necessary to build powerful applications on Chiliz Chain. From there, you can create a wide range of dApps, from token management to NFT-based utilities and interactive voting experiences.


# Prerequisites

To access CHZ, fan tokens, and other Chiliz Chain content on your users' wallet, you need to configure your dApp to access Chiliz Chain et allow users to connect their wallet to it.

## Setting up your environment

To achieve that, you can set your environment up with [Node.js](https://nodejs.org/) and the [Viem library](https://viem.sh/docs/installation) (you can use `npm install viem` once Node.js is installed).

## Instantiating the RPC client

Before starting a blockchain request, you MUST add this piece of code in order to initiate Viem and connect to Chiliz Chain via the RPC endpoint of your choice.&#x20;

You only need this code once in your codebase.

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import { createPublicClient, http } from 'viem'; // Initiate Viem

const client = createPublicClient({
  transport: http('https://YOUR-CHOSEN-RPC-ENDPOINT.com'), // Connect to Chiliz chain
});
```

{% endcode %}

There are several [Chiliz Chain RPC endpoints](https://docs.chiliz.com/develop/basics/connect-to-chiliz-chain/connect-using-rpc) that you can choose from.

## Implementing a "Connect Wallet" button to your dApp

Before interacting with Chiliz Chain, you must implement [a "Connect Wallet" button on you website or mobile app](https://docs.chiliz.com/develop/advanced/how-to-integrate-socios-wallet-in-your-dapp) in order for users to log in to you dApp.&#x20;

Once their wallet is connected, your dApp will be able to retrieve the user's wallet information, and possibly send data such as NFTs, tokens, etc.

{% hint style="info" %}
If you have any question or a specific configuration need, [please let us know](https://mediarex.atlassian.net/servicedesk/customer/portal/5/user/login?destination=portal%2F5%2Fgroup%2F12%2Fcreate%2F55): we will be happy to help you!
{% endhint %}

## Displaying the "Socios.com Wallet" option in the WalletConnect modal

{% hint style="info" %}
WalletConnect is one of the most common wallet-connection toolkit out there.&#x20;

When building a dApp, there's a good chance you will rely on it to connect with user wallets.

*NOTE: WalletConnect is now know as* [*Reown WalletKit*](https://reown.com/walletkit)*.*
{% endhint %}

If you want to allow your users to easily select the Socios.com Wallet, you can display it as an option in the WalletConnect pop-up. This pop-up appears in most "Connect Wallet" buttons online.

<figure><img src="/files/OP7JAxaRv6hxWRSFBRoF" alt=""><figcaption><p>Socios.com Wallet displayed as a featured wallet</p></figcaption></figure>

To display the Socios.com Wallet option, add the following line to the `featuredWalletsIds` option in your WalletConnect initialization code:

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```typescript
const SOCIOS_WALLET_ID = '56843177b5e89d4bcb19a27dab7c49e0f33d8d3a6c8c4c7e5274f605e92befd6'

createAppKit({
	[...],
	featuredWalletIds: [
		SOCIOS_WALLET_ID
	],
	[...],
})
```

{% endcode %}

{% hint style="info" %}
The `featureWalletIds` option is part of the `createAppKit` function. \
Learn more about it [in the WalletConnect/Reown documentation](https://docs.reown.com/appkit/next/core/options).
{% endhint %}

If your "Connect Wallet" code does not use WalletConnect/Reown, contact us so that we can help you out!


# Working with Tokens

{% hint style="warning" %}
Make sure to implement the [prerequisite code](/interact-with-chiliz-chain/prerequisites), or else the examples in this page will not work!
{% endhint %}

Of note: When working with official Fan Tokens in your project, you must use their correct addresses in your dApp. See here:

{% content-ref url="/pages/AsjhwFGVDIypIriOO3JD" %}
[Testnet Fan Token addresses](/interact-with-chiliz-chain/working-with-tokens/testnet-fan-token-addresses)
{% endcontent-ref %}

{% content-ref url="/pages/aMFOsskV5IZjmeqTCXkL" %}
[Mainnet Fan Token addresses](/interact-with-chiliz-chain/working-with-tokens/mainnet-fan-token-addresses)
{% endcontent-ref %}

### Prerequisite: ERC20ABI JSON file <a href="#prerequisite-survey-json-file" id="prerequisite-survey-json-file"></a>

{% hint style="success" %}
When working with Fan Tokens, and for some use-cases described in this page (the ones that import `ERC20ABI`), you will need the below **ERC20ABI.json** file saved in your project folder.

Make sure that you import that file in your code in order to achieve the wanted step (the samples already have the necessary `import` code).
{% endhint %}

{% file src="/files/ZVYFqAT5LIHmfxQ9udjO" %}

## Retrieve user token balances

You can retrieve how many tokens of a specific type (ERC-20) a user holds in their wallet.&#x20;

From there, you can create any scenario related to the balance. \
For instance, you can implement token-gating contents: giving access to certain content of your website only to holders of a certain token.

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import erc20ABI from './ERC20ABI.json';

const tokenAddress = '0xYourTokenAddress'; // Replace with the actual ERC-20 contract address
const userAddress = '0xUserWalletAddress'; // Replace with the user's wallet address

async function getTokenBalance() {
  const balance = await client.readContract({
    address: tokenAddress,
    abi: erc20ABI,
    functionName: 'balanceOf', // This is standard ERC-20 function to get balance
    args: [userAddress],
  });
  return balance.toString();
}

// Example usage
getTokenBalance().then(console.log);
```

{% endcode %}

{% hint style="success" %}
If you want to know if the user holds a specific token, make sure to check their wallet balance **and also to check their staked balance.** Read [how to know what's staked](/interact-with-chiliz-chain/working-with-staking#knowing-whats-staked).

Indeed, staked tokens are not taken into account in the wallet balance as they are not held in the wallet anymore: they are held on the staking smart-contract.
{% endhint %}

***

## Retrieve user CHZ balance

You can retrieve how many tokens of a specific native token a user has held in their wallet; for instance, CHZ on Chiliz Chain.

{% code lineNumbers="true" fullWidth="true" %}

```javascript
async function getNativeTokenBalance(address) {
  const balance = await client.getBalance({
    address,
  });
  return balance.toString();
}

// Example usage. Replace 0xUserWalletAddress with the actual user wallet address.
getNativeTokenBalance('0xUserWalletAddress').then(console.log);
```

{% endcode %}

***

## Send ERC-20 Tokens to a wallet

You can send any token held in your wallet to any other wallet.

{% hint style="success" %}
This is a code-based alternative to the `POST /admin/wallet/transfer/fan-token` endpoint, which was deprecated from the Socios.com API in Q1 2025.
{% endhint %}

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import { createWalletClient, privateKeyToAccount } from 'viem';

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);
const walletClient = createWalletClient({
  account,
  transport: http('YOUR-CHOSEN-RPC-ENDPOINT.com'),
});

async function sendTokens(to, amount) {
  const txHash = await walletClient.writeContract({
    address: '0xYourTokenAddress', // Replace with the ERC-20 token contract address
    abi: erc20ABI,
    functionName: 'transfer', // Standard ERC-20 function to transfer tokens
    args: [to, BigInt(amount * 1e18)],
  });
  return txHash;
}

// Example usage. Replace 0xRecipientAddress with the actual recepient wallet address, and 10 with the exact amount to send.
sendTokens('0xRecipientAddress', 10).then(console.log);
```

{% endcode %}

{% hint style="danger" %}
**Your private key must only be used in server-side code.** \
DO NOT release code on production with your private key shared on front-end side code.
{% endhint %}


# Testnet Fan Token addresses

| Name                | Ticker | Unwrapped                                    | Wrapped                                      |
| ------------------- | ------ | -------------------------------------------- | -------------------------------------------- |
| Paris Saint-Germain | PSG    | `0xb0Fa395a3386800658B9617F90e834E2CeC76Dd3` | `0x6D124526a5948Cb82BB5B531Bf9989D8aB34C899` |
| Tottenham Hotspur   | SPURS  | `0x9B9C9AAa74678FcF4E1c76eEB1fa969A8E7254f8` | `0x6199FF3173872E4dd1CF61cD958740A8CF8CAE75` |
| FC Barcelona        | BAR    | `0x7F73C50748560BD2B286a4c7bF6a805cFb6f735d` | `0x0fE14905415E67620BeA20528839676684260851` |
| AC Milan            | ACM    | `0x641d040dB51398Ba3a4f2d7839532264EcdCc3aE` | `0xa34e100D5545d5aa7793e451Fa4fdf5DaB84C94c` |
| OG                  | OG     | `0xEc1C46424E20671d9b21b9336353EeBcC8aEc7b5` | `0x55922807d03C61DE294b8794c25338d3AFc0EFF6` |
| Manchester City     | CITY   | `0x66F80ddAf5ccfbb082A0B0Fae3F21eA19f6B88ef` | `0x6350f61CDa7baea0eFAFF15ba10eb7A668E816da` |
| Arsenal             | AFC    | `0x44B190D30198F2E585De8974999a28f5c68C6E0F` | `0x75A5Db3a95d009a493a2a235A62097fd38D93bd4` |
| Flamengo            | MENGO  | `0x1CC71168281dd78fF004ba6098E113bbbCBDc914` | `0x8B67D9503B65c9f8d90AA5cAd9c25890918e5061` |
| Juventus            | JUV    | `0x945EeD98f5CBada87346028aD0BeE0eA66849A0e` | `0x141Da2E915892D6D6c7584424A64903050Ac4226` |
| Napoli              | NAP    | `0x8DBe49c4Dcde110616fafF53b39270E1c48F861a` | `0x7b57895dfbff9B096BFA75f54Bad64953717a37d` |
| Atletico De Madrid  | ATM    | `0xc926130FA2240e16A41c737d54c1d9b1d4d45257` | `0xAFdC9d9bD8baA0e0A7d636Ef8d27f28e94aE73c7` |


# Mainnet Fan Token addresses

<table><thead><tr><th width="215">NAME</th><th width="100.9765625">TICKER</th><th>ADDRESS</th><th>WRAPPED ADDRESS</th></tr></thead><tbody><tr><td>AC Milan</td><td>ACM</td><td><code>0xF9C0F80a6c67b1B39bdDF00ecD57f2533ef5b688</code></td><td><code>0x859DB9e2569bb87990482fC53E2F902E52585Ecb</code></td></tr><tr><td>Alfa Romeo Racing Orlen</td><td>SAUBER</td><td><code>0xcf6D626203011e5554C82baBE17dd7CDC4Ee86BF</code></td><td><code>0x9632E5D03Bb7568b68096AbF34B1367B87295d82</code></td></tr><tr><td>Alliance</td><td>ALL</td><td><code>0xc5C0d1E98D9b1398A37C82Ed81086674baEf2a72</code></td><td><code>0x1eb33b4243691f6FFbE0f77BBEa3be1C6b26E43E</code></td></tr><tr><td>Apollon Limmasol</td><td>APL</td><td><code>0xB407a167fE99eb97970e41b2608d0d9484C489C8</code></td><td><code>0xe265Db1EBEe1487Ea6EbA7ed9fdCECC8010c8e98</code></td></tr><tr><td>Argentine Football Association</td><td>ARG</td><td><code>0xd34625c1c812439229EF53e06f22053249D011f5</code></td><td><code>0x7475777609CE0Bd8e06b471B95AC5330511e03aE</code></td></tr><tr><td>Arsenal FC</td><td>AFC</td><td><code>0x1d4343d35f0E0e14C14115876D01dEAa4792550b</code></td><td><code>0x109523174dD4431dFd2628eaF9435cFD14dC6c2f</code></td></tr><tr><td>AS Monaco</td><td>ASM</td><td><code>0x371863096CF5685cD37AE00C28DE10b6edBab3Fe</code></td><td><code>0x7Ad193240F89b2f60c087eb9aebcf64139Dd7b89</code></td></tr><tr><td>AS Roma</td><td>ASR</td><td><code>0xa6610b3361c4c0D206Aa3364cd985016c2d89386</code></td><td><code>0x36C8239aabd0C6F7856B20aD9DEEb5080adAf0fb</code></td></tr><tr><td>Aston Martin Cognizant</td><td>AM</td><td><code>0x3757951792eDFC2CE196E4C06CFfD04027e87403</code></td><td><code>0xE51a3c216afB6e7c9BeBb4968CD4A8d1E0E99F77</code></td></tr><tr><td>Aston Villa</td><td>AVL</td><td><code>0x095726841DC9Bf395114Ac83f8fd42B176cFAd10</code></td><td><code>0xC8f1C7267F7c362A178EB94Ac74877ea2F6c034c</code></td></tr><tr><td>Atlas FC</td><td>ATLAS</td><td><code>0x936AE5911F49634fD7f4F7385dB1613c5E350EdE</code></td><td><code>0x7B9d4199368CA5F567999Fc35Aa3F6f86b18D2F2</code></td></tr><tr><td>Atlético Madrid</td><td>ATM</td><td><code>0xe9506F70be469d2369803Ccf41823713BAFe8154</code></td><td><code>0x7Ac8cAa7c42e13d31247B1F370E2CF0c242957e8</code></td></tr><tr><td>Atlético Mineiro</td><td>GALO</td><td><code>0xe5274Eb169E0e3A60B9dC343F02BA940958e8683</code></td><td><code>0xb7ff11AA7612e8c04A276dFEa3ff95fFc9724EA1</code></td></tr><tr><td>Aytemiz Alanyaspor</td><td>ALA</td><td><code>0x863f7537B38130F01a42E9e9406573B1F1e309F7</code></td><td><code>0x685Ba5134F373785263DB5a5BC5CFF686264500b</code></td></tr><tr><td>Bali United FC</td><td>BUFC</td><td><code>0xe87Cb1546D50F523057d3F94B07381dCE3F85eF9</code></td><td><code>0x53DB5c49CE9d0AB222e3a7458af140B78f857c81</code></td></tr><tr><td>Bologna FC</td><td>BFC</td><td><code>0x319067E6253FdbF183C27AbcAF31d45aD50E98fF</code></td><td><code>0x3Bce6c975Ed6Ed39aB80daC8774E5A6CE0E58515</code></td></tr><tr><td>BSC Young Boys</td><td>YBO</td><td><code>0x0Dc1776c56ffd3A046134Be6fDC23a3214359329</code></td><td><code>0xd14f7b7fD6D18A16c4f0c678E301a783D36a2BF0</code></td></tr><tr><td>Club Atlético Independiente</td><td>CAI</td><td><code>0x8A48AD8279318757ea7905b460816c4B92de447E</code></td><td><code>0xe6FfE9E1dE0E5bA375F10AeCA8E710225098D233</code></td></tr><tr><td>Club Deportivo Guadalajara</td><td>CHVS</td><td><code>0xF66288961A3495Ea9140fBD7c69E70a59Db08b16</code></td><td><code>0xB00d2468FB7471D080Ec301dcD1E12e334A1d9a3</code></td></tr><tr><td>Club Santos Laguna</td><td>SAN</td><td><code>0x44941A2d2049BE0ACB00Baf0A5dEE8931c33712E</code></td><td><code>0x39C0E77Cb84a893166cC0E943b8e22b7F56Dc9f5</code></td></tr><tr><td>Club Tigres UANL</td><td>TIGRES</td><td><code>0xf17b1E028537ABa705433f7ceBdca881B5c5B79E</code></td><td><code>0x2EA082e1053f05EfFEB8E28c350fa0ff8fe78538</code></td></tr><tr><td>Corinthians</td><td>SCCP</td><td><code>0x20BFeab58f8bE903753d037Ba7e307fc77c97388</code></td><td><code>0x89c2b844Da2B9b12eE704E2b544cEC064a9243a2</code></td></tr><tr><td>Crystal Palace FC</td><td>CPFC</td><td><code>0xA70bD29Bef2936765Fe33b0f4b0Cf8E947D75581</code></td><td><code>0x081232E5fee74ACa4C40bCe224C64e014A6AC245</code></td></tr><tr><td>Davis Cup</td><td>DAVIS</td><td><code>0xF50b3db1d498b69b0dc8ccc0b03643009a6bDA78</code></td><td><code>0x82741b8B13e95eBA9b60dDb8b368F9b793E92f3a</code></td></tr><tr><td>Dinamo Zagreb</td><td>DZG</td><td><code>0x6412aFDFdF2a465B2E2464A5F9d1743a9CFfd6fF</code></td><td><code>0xD97215C8515688d1573B058b9D30bA04A6Af6aa2</code></td></tr><tr><td>Endpoint</td><td>ENDCEX</td><td><code>0x3F521D391E2aD0093d3BFABB2516F1C57d73B4d1</code></td><td><code>0xAb445A85384287E5ea1265d3E393180d4b7aeA04</code></td></tr><tr><td>Esporte Clube Bahia</td><td>BAHIA</td><td><code>0xE92e152fC0ff1368739670a5175175154Ceeef42</code></td><td><code>0x55BD5c6b24F3c445f7EA813Cc37eD16473057073</code></td></tr><tr><td>Everton</td><td>EFC</td><td><code>0xaBEE61f8fF0eADd8D4ee87092792aAF2D9B2CA8e</code></td><td><code>0xFC8799E0895b3B92936075F3B1A4D1bF5F183166</code></td></tr><tr><td>FC Barcelona</td><td>BAR</td><td><code>0xFD3C73b3B09D418841dd6Aff341b2d6e3abA433b</code></td><td><code>0xbaAAEF59F4A6C11cC87FF75EAa7a386e753b2666</code></td></tr><tr><td>Flamengo</td><td>MENGO</td><td><code>0xD1723Eb9e7C6eE7c7e2d421B2758dc0f2166eDDc</code></td><td><code>0xa8732Dbb1985a570a1d98F57001E3c837046F618</code></td></tr><tr><td>Fluminense FC</td><td>FLU</td><td><code>0x86930777d43605C40bA786F7802778ff5413eFaB</code></td><td><code>0xD6E703752E5457825734f74eaF8813251A9970E4</code></td></tr><tr><td>Fortuna Sittard</td><td>FOR</td><td><code>0x4b56F121F769BBdeE3faBA6e8B9163E7cfFDd59a</code></td><td><code>0xf0f458B1E8Cd27d585De1baB5484B05C4d512a0E</code></td></tr><tr><td>Galatasaray S.K.</td><td>GAL</td><td><code>0x6DaB8Fe8e5d425F2Eb063aAe58540aA04e273E0d</code></td><td><code>0xCFc896fe8C791B6d1c085e69451E4B2f675a4927</code></td></tr><tr><td>Gaziantep F.K</td><td>GFK</td><td><code>0x2a5DbF10A9EB8d948AEF256FDE8e62F811624C4F</code></td><td><code>0x2bA57f4b99e9D2401381B2D2a1f60760CE3f1E82</code></td></tr><tr><td>Goztepe</td><td>GOZ</td><td><code>0x0E469D1C78421C7952E4D9626800DAd22F45361D</code></td><td><code>0x71103f7892c6c5BeCC135A22aFa9F021D905B750</code></td></tr><tr><td>Harlequins</td><td>QUINS</td><td><code>0x539e00D2487a06F3F08CDAF7Bf7A8b4a32C3a14E</code></td><td><code>0x1f9002a9964894213507966c1F352Dcf1ACb1484</code></td></tr><tr><td>Hashtag United</td><td>HASHTAG</td><td><code>0x7Be4Aebc9900d2C1b628530ffc59416A98420B15</code></td><td><code>0xE8C45FBbFdC1bA65A05D9Eb9C0ffF71900492802</code></td></tr><tr><td>Inter Milan</td><td>INTER</td><td><code>0xc727c9C0f2647CB90B0FCA64d8ddB14878716BeD</code></td><td><code>0xc587CF9ff27D7722ff4A3063abaFf81551803730</code></td></tr><tr><td>İstanbul Başakşehir</td><td>IBFK</td><td><code>0xd5FebD04baDd83e7ED56Ca093fD57655b737cd3e</code></td><td><code>0x3415C4bf4bDc284133831C2Ed414bC57Dbe5cFfc</code></td></tr><tr><td>Italian National Football Team</td><td>ITA</td><td><code>0x7483263CA24BFcfF716a21F4a9bbF2610BDD9Ec9</code></td><td><code>0x9EccD05BBA630cba3E6E119f9243AA649F443b19</code></td></tr><tr><td>JOHOR Southern Tigers</td><td>JDT</td><td><code>0x12129aD866906Ab5aa456ae1ebAeA9e8A13E8197</code></td><td><code>0xdc9cAd4bceb669E823aEB30e80F2d124b0a58b6b</code></td></tr><tr><td>Juventus</td><td>JUV</td><td><code>0x454038003a93cf44766aF352F74bad6B745616D0</code></td><td><code>0xaCf221C4f6C713459981660e3146e64Cba54e0B1</code></td></tr><tr><td>Leeds United</td><td>LUFC</td><td><code>0xF67A8a4299f7EBF0c58DbFb38941D0867f300C30</code></td><td><code>0x2D271B3826090872a7A79DD69FFe660367f8579d</code></td></tr><tr><td>Legia Warsaw</td><td>LEG</td><td><code>0x3Ce3946A68EB044C59AFe77dfdfdc71f19EB4328</code></td><td><code>0x58386A2d1c45D4c5349468892f5f73CA3E53EA22</code></td></tr><tr><td>Leicester Tigers</td><td>TIGERS</td><td><code>0x0b39ff3de07e8B6d2b97357d6F2A658ed7De52Cf</code></td><td><code>0x4b71E34bCb5feBa0dd51696863bcd792A84df196</code></td></tr><tr><td>Levante</td><td>LEV</td><td><code>0x69D65E72266b15C2b2ABcD69561399D9BD1843Ef</code></td><td><code>0xD37938861Bd995FdC016B6383ac7D78b345107BA</code></td></tr><tr><td>Made In Brasil</td><td>MIBR</td><td><code>0xa8206Af1e6a0289156d45B9d60e5bbD5d1fCf68d</code></td><td><code>0x57488F1C881b2D5832D61781e741D09c5b3410Fb</code></td></tr><tr><td>Manchester City</td><td>CITY</td><td><code>0x6401b29F40a02578Ae44241560625232A01B3F79</code></td><td><code>0x368F1EB2E4FA30C1C5957980C576Df6163575416</code></td></tr><tr><td>Millonarios FC</td><td>MFC</td><td><code>0xdEB5A271A67652A84dECb6278D70A6d6A18D7c3b</code></td><td><code>0xb1d0fADa44D28d31844241460d90C1775706126C</code></td></tr><tr><td>Napoli FC</td><td>NAP</td><td><code>0xbE7f1eBB1Fd6246844E093B04991ae0e66D12C77</code></td><td><code>0x9b24b3D55737BC28fdb21171ea5fD9eE50B136e6</code></td></tr><tr><td>Novara Calcio</td><td>NOV</td><td><code>0xE6BD000D6608E1E5d1476a96e7Cb63c335C595a9</code></td><td><code>0x5667DDD9764d1873D7a1bc15bc091a8B8a88EF1d</code></td></tr><tr><td>OG</td><td>OG</td><td><code>0x19cA0F4aDb29e2130A56b9C9422150B5dc07f294</code></td><td><code>0x07Eb6147263F2Fedb00002bAdaFc79ea769240f2</code></td></tr><tr><td>Palmeiras</td><td>VERDAO</td><td><code>0x971364Ec452958d4D65Ba8D508FAa226d7117279</code></td><td><code>0x6dB3ECA64DC5B789a70571BD81332864bA327A56</code></td></tr><tr><td>Paris Saint-Germain</td><td>PSG</td><td><code>0xc2661815C69c2B3924D3dd0c2C1358A1E38A3105</code></td><td><code>0x476eF844B3E8318b3bc887a7db07a1A0FEde5557</code></td></tr><tr><td>Persatuan Sepakbola Indonesia Bandung</td><td>PERSIB</td><td><code>0xC34BfBA5dB50152eF3312348A814D24F85748d64</code></td><td><code>0x22a82491C4bA35E6910213811ddE4F8702aE0709</code></td></tr><tr><td>Persija Jakarta</td><td>PRSJ</td><td><code>0xB6C7e13752c2d5C94B88A522696b6Dec380971eF</code></td><td><code>0x212dCc7296FeE75287693E906Ef5951331c68ab5</code></td></tr><tr><td>Portugal National Team</td><td>POR</td><td><code>0xFFAD7930B474D45933C93b83A2802204b8787129</code></td><td><code>0x804C701c3d548d68773e4E06c76C03aFa0e32d42</code></td></tr><tr><td>Professional Fighters League</td><td>PFL</td><td><code>0xde05490B7AC4B86e54eFf43f4F809C3a7Bb16564</code></td><td><code>0x9b18841FE851f5B4b9400E67602eC2FE65aaaE0a</code></td></tr><tr><td>Racing Club</td><td>RACING</td><td><code>0x06Ed14A885D0710118fc20D51EfDC151a48005b3</code></td><td><code>0x7CB4FFbf64CD58fE6dC57ED8011b65b73691F0AD</code></td></tr><tr><td>Real Sociedad</td><td>RSO</td><td><code>0xdd03a533d6a309aFFF3053FE9Fc6C197324597bb</code></td><td><code>0xeF571542DcF394Da8B5190F75A20dacC07fAC741</code></td></tr><tr><td>Roush Fenway Keselowski</td><td>ROUSH</td><td><code>0xBA20eF1670393150d1C1b135F45043740ec3a729</code></td><td><code>0x369C0bf5B24cfc088BD1E634ecDF95F786DBF5CB</code></td></tr><tr><td>Samsunspor</td><td>SAM</td><td><code>0xfC21C38f4802Ab29Aed8cc7367542A0955CfA9D7</code></td><td><code>0x72e24AaDEE54E65152C14246D2C62C1D42804764</code></td></tr><tr><td>Sao Paulo FC</td><td>SPFC</td><td><code>0x540165b9dFdDE31658F9BA0Ca5504EdA448BFfd0</code></td><td><code>0x60175b07658694FC1c16578376c439879C05d1Cb</code></td></tr><tr><td>Saracens</td><td>SARRIES</td><td><code>0x753DDA10c7b3069f0C90837dC3755c7c40A81B8c</code></td><td><code>0xCcE302af2BBe84b5c44C3A460165816EE2fd7fF3</code></td></tr><tr><td>Sevilla FC</td><td>SEVILLA</td><td><code>0x60a5E1f5f0071C5d870bB0A80B411BDe908AD51e</code></td><td><code>0xb71597e18D9933b38a56817Ed74C64618232e325</code></td></tr><tr><td>Sint-Truidense Voetbalvereniging</td><td>STV</td><td><code>0xe446d966Ba9a36E518cF450AbbD22f45688107Da</code></td><td><code>0x6d58211888D381D6Fd3D344A7a33789cE0628b01</code></td></tr><tr><td>SL Benfica</td><td>BENFICA</td><td><code>0xad7c869F357B57BB03050183d1BA8eC465CD69Dc</code></td><td><code>0x8b11453f790726eC863422D47c2bDF6222dD0F2D</code></td></tr><tr><td>Sport Club Internacional</td><td>SACI</td><td><code>0x3175e779b42D35e2C9EeafadCf5B6E6ec6E4f910</code></td><td><code>0xE41a78C047E455C3f57F610091D0dE023A7b3D0B</code></td></tr><tr><td>Stade Francais Paris</td><td>SFP</td><td><code>0x2a89f8af25B01B837d67be3B1A162A663F77b26E</code></td><td><code>0x802B51D1Aa89C7222993463Ade8600cF08700DfF</code></td></tr><tr><td>Team Heretics</td><td>TH</td><td><code>0x06B4213774DD069cF603ad11770B52F1E98160a7</code></td><td><code>0x6c5e381aF6E3B237F8471A7e1448A4CdF82d3447</code></td></tr><tr><td>The Sharks</td><td>SHARKS</td><td><code>0x1f5Ed1182b673338ECff0eeaB13ed79cEaf775f5</code></td><td><code>0x8b8454ad0bc75C3C4bECb250b48D9a2072Fd55E3</code></td></tr><tr><td>Tottenham Hotspur</td><td>SPURS</td><td><code>0x93D84Ff2c5F5a5A3D7291B11aF97679E75eEAc92</code></td><td><code>0xf6Bebad8bE7bb9ce05b9A71b9ab62E2e7fA58e9f</code></td></tr><tr><td>Trabzonspor</td><td>TRA</td><td><code>0x304193f18f3B34647ae1f549fc825A7e50267c51</code></td><td><code>0x80E5DCCABC8566d4b12812142A6609d6b9dd84CF</code></td></tr><tr><td>Udinese Calcio</td><td>UDI</td><td><code>0xd2571bb5E84F1a3ac643b6be1dD94fC9fb97041d</code></td><td><code>0xCE1E295c23D6c99909A414b0dDE447c15bB4Db7D</code></td></tr><tr><td>Ultimate Fighting Championship</td><td>UFC</td><td><code>0x0ffa63502f957b66e61F87761cc240e51C74cee5</code></td><td><code>0xa698a6D7275A461D6F2D425E31dAB4a61a171AFd</code></td></tr><tr><td>Universidad de Chile</td><td>UCH</td><td><code>0xA082EC45aF038100D4989636A4A5E52fD7e5C636</code></td><td><code>0x1A21a5C735a48FdE12637D85501205A85FA9aB37</code></td></tr><tr><td>Valencia</td><td>VCF</td><td><code>0xba0c26485b1909f80476067272d74A99Cc0E1D57</code></td><td><code>0xf9ae77D7658ad1a1Ff49Ca4D082fEDb680A83373</code></td></tr><tr><td>Vasco da Gama</td><td>VASCO</td><td><code>0x6d72034D7508D16988bf84638D51592A8c02887b</code></td><td><code>0x2EAe5689908ac76996B70B48d5CE5d2f2fCC09e0</code></td></tr><tr><td>Vitality</td><td>VIT</td><td><code>0x1754bbc90F8C004EDBaCC59e41AA4be7a36B5D5b</code></td><td><code>0x82E159F2704A9d00f2079be89Dc1d6c499536957</code></td></tr></tbody></table>


# Working with NFTs

{% hint style="warning" %}
Make sure to implement the [prerequisite code](/interact-with-chiliz-chain/prerequisites), or else the examples in this page will not work!
{% endhint %}

## Prerequisite: erc721ABI JSON file

{% hint style="success" %}
When working with NFT, and for some use-cases described in this page (the ones that import `erc721ABI`), you will need the below **ERC721Abi.json** file saved in your project folder.&#x20;

Make sure that you import that file in your code in order to achieve the wanted step (the samples already have the necessary `import` code).
{% endhint %}

{% file src="/files/06Qy8xKMqR0mnvrZXqru" %}

## Retrieve user NFT list

To retrieve all NFTs held in user wallet, you need a third-party tool or API.

In this example, we use [Nansen API's `GET /address/portfolio` endpoint](https://api-docs.nansen.ai/reference/get_address-portfolio-1).

{% code lineNumbers="true" fullWidth="true" %}

```javascript
const options = {method: 'GET', headers: {accept: 'application/json'}};

fetch('https://api.nansen.ai/v1/address/portfolio', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

{% endcode %}

## Retrieve user NFT details

Once you know the NFT's smart-contract address (using the code above), you can get all its metadata:

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import erc721ABI from './ERC721ABI.json';

const contractAddress = '0xYourNFTAddress'; // Replace with the actual contract address

async function getNFTMetadata(tokenId) {
    const tokenURI = await client.readContract({
        address: contractAddress, // Contract address of the NFT
        abi: erc721ABI,
        functionName: 'tokenURI', // Standard ERC-721 function to get metadata uri
        args: [tokenId], // User's address whose balance you want to check
    });

    const metadataResponse = await fetch(tokenURI);
    const metadata = await metadataResponse.json();
    console.log(metadata);
}

// Example usage: Get metadata for a specific token (e.g., token ID 1)
getNFTMetadata(1);
```

{% endcode %}

## Retrieve user NFT balance

This code will allow you to check how many NFTs from a specific collection a user holds.

It is much lighted than the "Retrieve user NFT list" example that uses Nansen shown above.

{% code lineNumbers="true" fullWidth="true" %}

```javascript
import erc721ABI from './ERC721ABI.json';

async function getNFTBalance() {
  const balance = await client.readContract({
    address: '0xYourNFTAddress', // Replace with the actual NFT contract address
    abi: erc721ABI,
    functionName: 'balanceOf', // Standard ERC-721 function to get balance
    args: ['0xUserWalletAddress'], // User's address whose NFT balance you want to check
  });
  return balance.toString();
}

// Example usage
getNFTBalance().then(console.log);
```

{% endcode %}


# Working with Transactions

{% hint style="warning" %}
Make sure to implement the [prerequisite code](/interact-with-chiliz-chain/prerequisites), or else the examples in this page will not work!
{% endhint %}

## Retrieve a user transaction details

You can retrieve details about a specific transaction.\
NOTE: This example only provides *estimated* gas fees details for the transaction.

{% hint style="success" %}
This is a code-based alternative to the `GET /user/wallet/{transactionId}` endpoint, which was deprecated from the Socios.com API in Q1 2025.
{% endhint %}

{% code lineNumbers="true" fullWidth="true" %}

```javascript
async function getTransaction(txHash) {
  const transaction = await client.getTransaction({
    hash: txHash, // Replace with the actual transaction hash
  });
  return transaction;
}

// Example usage
getTransaction('0xTransactionHash').then(console.log);
```

{% endcode %}

## Retrieve a user transaction receipt

You can retrieve a specific transaction receipt.\
NOTE: This example provides definitive gas fees details for the transaction.

{% code lineNumbers="true" fullWidth="true" %}

```javascript
async function getTransactionReceipt(txHash) {
  const transactionReceipt = await client.getTransactionReceipt({
    hash: txHash, // Replace with the actual transaction hash
  });
  return transactionReceipt;
}

// Example usage
getTransactionReceipt('0xTransactionHash').then(console.log);
```

{% endcode %}


# Working with Polls

{% hint style="warning" %}
Make sure to implement the [prerequisite code](/interact-with-chiliz-chain/prerequisites), or else the examples in this page will not work!
{% endhint %}

## Prerequisite: Survey3ABI JSON file

{% hint style="success" %}
When working with polls, and for some use-cases (the ones that import `survey3ABI`), you will need the below **survey3ABI.json** file saved in your project folder.&#x20;

Make sure that you import that file in your code in order to achieve the wanted step (the samples already have the necessary `import` code).
{% endhint %}

{% file src="/files/82fVity5fM16ocDE5TTC" %}

## Retrieve poll question

You can retrieve any poll question from Chiliz Chain, provided that you have the poll's contract address.

{% hint style="success" %}
Before you run this blockchain call, you need to know the poll's ID.&#x20;

You can use the `GET /polls/` endpoint to retrieve it. [See this documentation](/partner-api/api-reference/polls-api/polls-api-endpoints#get-polls).
{% endhint %}

{% code lineNumbers="true" fullWidth="true" %}

```javascript
import { createPublicClient, http } from 'viem';
import survey3ABI from './survey3ABI.json';

const client = createPublicClient({
  transport: http('YOUR-RPC.com'),
});

const pollAddress = '0xPollAddress'; // Replace with the actual poll contract address

// Returns question text
async function getQuestion() {
  const question = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'question', // Function to retrieve the question
    args: [],
  });
  return question;
}

// Example usage
getQuestion().then(console.log);
```

{% endcode %}

## Retrieve poll answers

You can retrieve all poll answers from Chiliz Chain, provided that you have the poll's contract address.

{% hint style="warning" %}
As of May 2025, you cannot retrieve poll answers media (such as pictures and videos) via this blockchain call.&#x20;

To do that, you must use the Socios.com API `GET /polls/` endpoint, [documented here](/partner-api/api-reference/polls-api/polls-api-endpoints#get-polls).

We are working on this for the next version of our survey smart contract. This is planned for end of 2025.
{% endhint %}

{% code lineNumbers="true" fullWidth="true" %}

```javascript
import { createPublicClient, http } from 'viem';
import survey3ABI from './survey3ABI.json';

const client = createPublicClient({
  transport: http('YOUR-RPC.com'),
});

const pollAddress = '0xPollAddress'; // Replace with the actual poll contract address

// Returns a list of answers with id, total votes and total amount of tokens used in votes
async function getAnswers() {
  const answers = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getAnswers', // Function to retrieve the answers
    args: [],
  });
  return answers;
}

// Example usage
getAnswers().then(console.log);
```

{% endcode %}

## Allow a user to vote on a poll

You can allow a logged-in user to vote a specific Socios.com poll.&#x20;

We recommend to implement [Reown's Wallet Kit](/interact-with-chiliz-chain/prerequisites) (previously called WalletConnect) in order to have your users logged in via their web3 wallet. \
Once they are logged in, if they have a Fan Token of the team the poll belongs to, they will be able to vote on that poll.&#x20;

We also recommend to check whether the user has a token or not before allowing them to vote, because if they don't, their vote will be rejected at the smart contract level.

### Approve token staking

#### Prerequisite: erc20ABI JSON file

{% hint style="success" %}
When approving token staking, you will need the below **erc20ABI.json** file saved in your project folder.&#x20;

Make sure that you import that file in your code in order to achieve the wanted step (the samples already have the necessary `import` code).
{% endhint %}

{% file src="/files/ZVYFqAT5LIHmfxQ9udjO" %}

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import { createWalletClient, privateKeyToAccount } from 'viem';
import erc20ABI from './erc20ABI.json';

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);
const walletClient = createWalletClient({
  account,
  transport: http('YOUR-RPC.com'),
});

async function approveTokens(stakingContractAddress) {
  const txHash = await walletClient.writeContract({
    address: '0xYourTokenAddress', // Replace with the ERC-20 token contract address
    abi: erc20ABI,
    functionName: 'approve', // Standard ERC-20 function to approve tokens
    args: [stakingContractAddress, BigInt(1e18)], // For 0 decimal tokens, use BigInt(1) for 1 token
  });
  return txHash;
}

// Example usage. Replace 0xStakingContractAddress with the actual staking smart contract address.
approveTokens('0xStakingContractAddress').then(console.log);
```

{% endcode %}

{% hint style="danger" %}
**Your private key must only be used in server-side code.** \
DO NOT release code on production with your private key shared on front-end side code.
{% endhint %}

### Vote on poll

{% hint style="success" %}
This is a code-based alternative to the `POST /poll/{pollId}/vote` endpoint, which was deprecated from the Socios.com API in Q1 2025.
{% endhint %}

{% code lineNumbers="true" fullWidth="true" %}

```javascript
import { createWalletClient, privateKeyToAccount } from 'viem';

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);
const walletClient = createWalletClient({
  account,
  transport: http('YOUR-RPC.com'),
});

async function vote(id, weight) {
  const txHash = await walletClient.writeContract({
    address: '0xPollAddress', // Replace with the poll contract address
    abi: survey3ABI, // Poll contract ABI
    functionName: 'vote', // Function to cast the vote
    args: [id, BigInt(weight)], // Replace 'id' with answer id and 'weight' with the amount of tokens that should be used to cast the vote
  });
  return txHash;
}

// Example usage
vote('dab3d446-959f-47e7-8789-f618d969de1e', 1).then(console.log);
```

{% endcode %}

{% hint style="danger" %}
**Your private key must only be used in server-side code.** \
DO NOT release code on production with your private key shared on front-end side code.
{% endhint %}

## Retrieve user vote on a poll

You can know whether a user has already voted on a specific poll or not, and if they have then you can retrieve which answer they have selected.

{% hint style="success" %}
This is a code-based alternative to the `GET /poll/{pollId}` endpoint, which was deprecated from the Socios.com API in Q1 2025.
{% endhint %}

{% code lineNumbers="true" fullWidth="true" %}

```javascript
import { createPublicClient, http, keccak256 } from 'viem';
import survey3ABI from './survey3ABI.json';

const client = createPublicClient({
  transport: http('YOUR-RPC.com'),
});
const pollAddress = '0xPollAddress'; // Replace with the actual poll contract address
const userAddress = '0xUserAddress'; // Replace with the user's wallet address

// Returns hashes of answerIds that the user voted on
async function getUserVoteHashes() {
  const votes = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll contract ABI
    functionName: 'getUserAnswers', // Function to retrieve the answers that the user voted on
    args: [userAddress], // User's address whose votes you want to fetch
  });
  return votes;
}

// Returns votes in plain text
async function getUserVotesPlainText() {
  // fetch all answers
  const answers = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll contract ABI
    functionName: 'getAnswers', // Function to retrieve the answers
    args: [], // User's address whose votes you want to fetch
  });

  // fetch user's votes
  const votes = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getUserAnswers', // Function to retrieve the answers that the user voted on
    args: [userAddress], // User's address whose votes you want to fetch
  });

  // filter answers, return the ones that the user voted on
  const plainTextVotes = answers.filter(a => votes.includes(keccak256(a.id)));

  return plainTextVotes;
}

// Example usage
getUserVotesPlainText().then(console.log);
getUserVoteHashes().then(console.log);
```

{% endcode %}


# Working with Staking

{% hint style="warning" %}
Make sure to implement the [prerequisite code](/interact-with-chiliz-chain/prerequisites), or else the examples in this page will not work!
{% endhint %}

Socios.com users have two possibilities when staking do in-app:

* Staking Fan Tokens.
* Staking CHZ.&#x20;

Furthermore, Socios.com partners can implement the Socios.com Fan Token staking mechanism on their own website.&#x20;

Of note: When working with CHZ tokens in your project, you must use thecorrect addresses in your dApp. See here:

{% content-ref url="/pages/D4uftGbnzOmnKXbxjg5X" %}
[Testnet staking smartcontracts](/interact-with-chiliz-chain/working-with-staking/testnet-staking-smartcontracts)
{% endcontent-ref %}

{% content-ref url="/pages/OwDloA38QmQujOKtWz0J" %}
[Mainnet staking smartcontracts](/interact-with-chiliz-chain/working-with-staking/mainnet-staking-smartcontracts)
{% endcontent-ref %}

## About "Stake & Earn"

By staking their Fan Tokens through their Socios.com Wallet, Socios.com users can earn Reward Points on a daily basis, and possibly get quick access to great Socios.com rewards and activities!

Each staked Fan Token will join an existing pool of rewards points, made of all the Fan Tokens staked by all Socios.com users.

The pool then works for all users, and the more Fan Tokens you have staked, the more reward points you can obtain in return.

{% hint style="info" %}
Fan Token staking is also possible from wallets other than Socios.com Wallet.&#x20;

This allows anyone to contribute to the Fan Token ecosystem, but staking from non-Socios wallets cannot earn Socios.com reward points.
{% endhint %}

{% hint style="success" %}
There is only one smart contract address to stake any of the Socios.com Fan Tokens: `0x5ff7f9724fd477d9a07dcdb894d0ca7f8fae1501`
{% endhint %}

## Implementing Socios.com staking/unstaking on your own site

Socios.com partners can implement Fan Token staking right into their own platform.&#x20;

This is done through a specific smart contract created by the Socios.com team. This Staking smart contract has 5 main features:

* Staking
* Locking
* Processing the locks
* Unstaking
* Claiming

To implement staking, unstaking, and the other necessary fixtures, we provide you with the following sample code listing, ready for you to adapt to your own codebase.

### Prerequisite: StakingABI JSON file <a href="#prerequisite-survey-json-file" id="prerequisite-survey-json-file"></a>

{% hint style="success" %}
When working with staking, and for some use-cases described in this page (the ones that import `stakingABI`), you will need the below **StakingABI.json** file saved in your project folder.

Make sure that you import that file in your code in order to achieve the wanted step (the samples already have the necessary `import` code).
{% endhint %}

{% file src="/files/OPONM7yZt7nqyAy9oRX6" %}

### Setting up your Chiliz Viem Client

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import { createPublicClient, http, createWalletClient } from 'viem'
import { chiliz, spicy } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts';

const publicClient = createPublicClient({
	chain: chiliz, // chiliz (mainnet) or spicy (testnet)
	transport: http() // you can overwrite the transport URL provided by Chain object here 
})

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);
const walletClient = createWalletClient({
	account: '0x',
	chain: chiliz, // chiliz (mainnet) or spicy (testnet)
	transport: http()
})
```

{% endcode %}

{% hint style="danger" %}
**Your private key must only be used in server-side code.** \
DO NOT release code on production with your private key shared on front-end side code.
{% endhint %}

### Staking

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import stakingABI from './StakingABI.json';

async function stake(amount, tokenAddress) {
  const txHash = await walletClient.writeContract({
    address: '0xFanTokenStakingAddress', // Replace with the Fan Token Staking contract address
    abi: stakingABI,
    functionName: 'stake', // Function to stake tokens
    args: [amount, tokenAddress],
  });
  return publicClient.waitForTransactionReceipt({ hash: txHash });
}

// Example usage. Replace 10 with the exact amount to stake, and 0xFanTokenAddress with the actual Fan Token contract address.
stake(10, '0xFanTokenAddress',).then(console.log);
```

{% endcode %}

### Knowing what's staked

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import stakingABI from './StakingABI.json';

async function getStakeDataLatest(staker, fanToken, perEventType) {
  const stakeData = await publicClient.readContract({
    address: '0xFanTokenStakingAddress', // Replace with the Fan Token Staking contract address,
    abi: stakingABI,
    functionName: 'getStakeDataLatest',
    args: [staker, fanToken, perEventType],
  });
  return stakeData;
}

// Example usage, Replace 0xStakerWalletAddress with the actual staker wallet address, and 0xFanTokenAddress with the actual Fan Token contract address.
getStakeDataLatest('0xStakerWalletAddress', '0xFanTokenAddress').then(console.log);
```

{% endcode %}

### Unstaking

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import stakingABI from './StakingABI.json';

async function unstake(amount, tokenAddress) {
  const txHash = await walletClient.writeContract({
    address: '0xFanTokenStakingAddress', // Replace with the Fan Token Staking contract address
    abi: stakingABI,
    functionName: 'unstake', // Function to unstake tokens
    args: [amount, tokenAddress],
  });
  return publicClient.waitForTransactionReceipt({ hash: txHash });
}

// Example usage. Replace 10 with the exact amount to unstake, and 0xFanTokenAddress with the actual Fan Token contract address.
unstake(10, '0xFanTokenAddress',).then(console.log);
```

{% endcode %}

### Checking the cooldown period

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import stakingABI from './StakingABI.json';

async function getCooldownPeriod() {
  const cooldownPeriod = await publicClient.readContract({
    address: '0xFanTokenStakingAddress', // Replace with the Fan Token Staking contract address,
    abi: stakingABI,
    functionName: 'unstakePeriod', // The function that returns the unstake period.
    args: [],
  });
  return cooldownPeriod.toString();;
}

// Example usage.
getCooldownPeriod().then(console.log);
```

{% endcode %}

### Claiming (after cooldown period)

{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```javascript
import stakingABI from './StakingABI.json';

async function claim(amount, tokenAddress) {
  const txHash = await walletClient.writeContract({
    address: '0xFanTokenStakingAddress', // Replace with the Fan Token Staking contract address
    abi: stakingABI,
    functionName: 'claim', // Function to claim tokens
    args: [amount, tokenAddress],
  });
  return publicClient.waitForTransactionReceipt({ hash: txHash });
}

// Example usage. Replace 0xFanTokenAddress with the actual Fan Token contract address.
claim('0xFanTokenAddress',).then(console.log);
```

{% endcode %}


# Testnet staking smartcontracts

## Chiliz governance staking

Chiliz (CHZ) stakingPool contract: `0x0000000000000000000000000000000000007001`&#x20;

Chiliz (CHZ) staking contract: `0x0000000000000000000000000000000000001000`

***

## Socios Fan Token staking

Fan Token staking: `0x9Fed66a22626B10d2fFE8d24099Da0a1A2cd5318`


# Mainnet staking smartcontracts

## Chiliz governance staking

Chiliz (CHZ) stakingPool contract: `0x0000000000000000000000000000000000007001`&#x20;

Chiliz (CHZ) staking contract: `0x0000000000000000000000000000000000001000`

***

## Socios Fan Token staking

Fan Token staking: `0x5FF7f9724Fd477d9a07DCdb894d0CA7F8FAe1501`


# Overview

{% hint style="warning" %}
**2024-12-09 - ANNOUNCEMENT FOR SOCIOS.COM API DEVELOPERS**

In Q1 2025, the Chiliz team will decommission several endpoints and features from the Socios.com API. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We provide you with alternatives right here on this documentation site.
{% endhint %}

The Socios.com API makes it possible to create personalized and engaging fan experiences, right in your own space.

By getting access to a subset of information about your users along with our fan-centric features, you can create a personalized experience that not only captivates your visitors but also fosters a deeper connection, inspiring loyalty and enhancing overall user satisfaction.

{% hint style="info" %}
Accessing Socios.com fan data requires you to get explicit consent from fans.
{% endhint %}

Here are some ways the API can be used: &#x20;

* **Bring tailored rewards**\
  Offer your fans the convenience of logging into their Socios.com account directly from your platform. By making it possible for fans to access their wallets through your website or app, you can tailor rewards based on their token holdings.&#x20;
* **Offer a customized user interface**\
  With consent to access Socios.com users' information, wallets, or NFTs, you have the opportunity to customize the user interface of your platform and provide bespoke workflows to the user's CHZ or fan token balance. \
  This way, you can create unique and special experiences, exclusively designed for each user.
* **Rebrand the Socios.com experience**\
  Once the Socios.com APIs are integrated on your side, you have the liberty to customize the Socios.com experience in alignment with your brand's style and aesthetics. \
  Reinforce your brand identity while providing an enriched Socios.com experience to your fans!
* ... and more!

In short, the Socios.com API allows you to give sports fans the ability to access their Socios.com accounts and engage with unique Socios.com features, without leaving your digital environment!


# 2025 API Update Overview

{% hint style="warning" %}
**2024-12-09 - ANNOUNCEMENT FOR SOCIOS.COM API DEVELOPERS**

In Q1 2025, the Chiliz team will decommission several endpoints and features from the Socios.com API. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We provide you with alternatives right here on this documentation site.
{% endhint %}

This page is meant to inform on the way the Socios.com API is going to evolve in Q1 2025.

The API team is committed to help you transition your code based on the Socios.com API to new ways of providing the same functionality, thus minimizing the impact on your users.

## Overview of API endpoint updates

{% hint style="success" %}
Whenever applicable, we provide an alternative to the Socios.com API endpoint that is removed, using TypeScript code.
{% endhint %}

### Data API

See details in [Data API reference page](/partner-api/api-reference/data-api/data-api-endpoints).

| Endpoints             | Post-update status |
| --------------------- | ------------------ |
| `GET /countries`      | ✅ Kept as-is.      |
| `GET /sports`         | ✅ Kept as-is.      |
| `GET /leagues`        | ✅ Kept as-is.      |
| `GET /fantokens`      | ✅ Kept as-is.      |
| `GET /fantokens/rate` | ✅ Kept as-is.      |

### NFT API

See details in [NFT API reference page](/partner-api/api-reference/nft-api/nft-api-endpoints).

| Endpoints                                      | Post-update status           |
| ---------------------------------------------- | ---------------------------- |
| `GET /user/nfts`                               | ♻️ Removed with alternative. |
| `GET /nft/{id}`                                | ♻️ Removed with alternative. |
| `GET /nfts/smartcontract/{smartContractId}`    | ❌ Removed.                   |
| `POST /admin/nft/smart-contract`               | ❌ Removed.                   |
| `POST /admin/nft/collectible-definition`       | ❌ Removed.                   |
| `POST /admin/nft/{collectibleId}/asset-upload` | ❌ Removed.                   |
| `POST /admin/nft/{collectibleDefinition}/mint` | ❌ Removed.                   |

### Ping API

See details in [Ping API reference page](/partner-api/api-reference/ping-api).

| Endpoint    | Post-update status |
| ----------- | ------------------ |
| `GET /ping` | ✅ Kept as-is.      |

### Polls API

See details in [Polls API reference page](/partner-api/api-reference/polls-api/polls-api-endpoints).

| Endpoints                       | Post-update status |
| ------------------------------- | ------------------ |
| `GET /polls`                    | ✅ Kept as-is.      |
| `GET /poll/{pollId}`            | ✅ Kept as-is.      |
| `POST /user/polls`              | ❌ Removed.         |
| `POST /user/polls/history`      | ❌ Removed.         |
| `POST /user/poll/{pollId}/vote` | ❌ Removed.         |
| `POST /user/poll/{pollId}`      | ❌ Removed.         |

### Rewards API

See details in [Reward API reference page](/partner-api/api-reference/rewards-api/rewards-api-endpoints).

| Endpoints                 | Post-update status |
| ------------------------- | ------------------ |
| `GET /rewards`            | ✅ Kept as-is.      |
| `GET /rewards/{rewardId}` | ✅ Kept as-is.      |
| `GET /reward-categories`  | ✅ Kept as-is.      |

### User API

See details in User API reference page.

| Endpoints      | Post-update status |
| -------------- | ------------------ |
| `GET /user/me` | ✅ Kept as-is.      |

### Wallet API

See details in Wallet API reference page.

| Endpoints                                        | Post-update status          |
| ------------------------------------------------ | --------------------------- |
| `GET /user/wallet`                               | ♻️ Removed with alternative |
| `POST /wallet/sign-message`                      | ❌ Removed.                  |
| `GET /user/wallet/{transactionId}`               | ♻️ Removed with alternative |
| `GET /user/wallet/transaction-history/fan-token` | ♻️ Removed with alternative |
| `POST /admin/wallet/transfer/fan-token`          | ♻️ Removed with alternative |


# Prerequisites

Before you get started...

Prior to working on integrating the Socios.com API into your project, there are a few requirements to address.&#x20;

Here's a checklist to help you get started.

## **1. Get Your Free Access**

{% hint style="info" %}
We advise you to reach out to your account manager or key point of contact at Socios.com. \
They will guide you through the process of getting your access to the Socios.com API Manager tool.&#x20;
{% endhint %}

To obtain your Socios.com API access:

1. Access the [Chiliz Help Centre](https://mediarex.atlassian.net/servicedesk/customer/portal/5).
   1. Submit your email to create an account on the platform.

      <figure><img src="/files/9WWPx6rmRvrCtgN45Z1a" alt="" width="375"><figcaption></figcaption></figure>

      *If you already have an Atlassian account, click "Continue with Atlassian account".*
   2. Choose either "Companies" or "Individuals", depending on your situation.

      <figure><img src="/files/AOPjgUbdzGVpUCexPiVt" alt="" width="563"><figcaption></figcaption></figure>
2. Click on "Complete API Due Diligence" and fill in the form.
3. Click on "API Terms & Conditions" and fill in the form.&#x20;

The Socios.com team will contact you shortly.

## **2. Create Your Application**

Once you have your API access, you need to create a new OAuth 2.0 application in your API settings. You can do this by visiting the [Socios.com Developer Portal](https://partner.socios.com/devportal/apis). Log in, navigate to your API settings, and create a new application. See our [Quick Start](/partner-api/quick-start) for more.

{% hint style="danger" %}
Make sure to use our production environment since the sandbox is under construction.
{% endhint %}

## **3. Familiarise Yourself With Our URLs**

You should be aware of the following URLs to smoothly operate with the Socios.com  API:

* **API Base URL**\
  [https://api-public.socios.com](<https://api-public.socios.com >) \
  This is the base URL that you'll use to interact with our APIs.
* **Authorisation URL**\
  [https://partner.socios.com/oauth2/authorize ](<https://partner.socios.com/oauth2/authorize >)\
  This is the URL used for authorising your application with OAuth2.&#x20;
* **Access Token URL**\
  [https://partner.socios.com/oauth2/token ](<https://partner.socios.com/oauth2/token >)\
  This is the URL to use when requesting an access token. \
  The access token is used to authorise your API requests.
* **Revoke Token URL**\
  [https://partner.socios.com/oauth2/revoke ](<https://partner.socios.com/oauth2/revoke >)\
  This is the URL to use when needing to revoke your token, for any reason.

With these prerequisites in place, you should be ready to begin using the Socios.com API. If you have any questions or need any further information, feel free to reach out to your point of contact.


# Quick start

This page guides you on how to create, manage, and use your API access effectively.

A large portion of API management happens in the Socios.com API Manager. \
It requires you to do the following before you can use one of our APIs:

1. Create a shell application that will host the API parameters you intend to use.
2. Generate production keys for the application, and select the type of API access you want to have for this application.
3. Subscribe the application to the relevant API.

{% hint style="info" %}
Applications allow you to:

* Generate and use a single key for multiple APIs.
* Subscribe multiple times to a single API with different Service Level Agreements (SLAs)/business plans which operate on a per access token basis.
  {% endhint %}

## Step 1: Log in

If you're a new user and still do not have access to Socios.com APIs yet, please contact your dedicated Partnership Manager, or follow Due Diligence. In time, you will get your access code to log into the [Socios.com API Manager](https://partner.socios.com/devportal/apis).

Once you've logged in, you have access to all of our APIs.

<figure><img src="/files/4OvY6XwflY0sxjZJpazn" alt=""><figcaption></figcaption></figure>

## Step 2: Create an application

You must create an application in order to use the Socios.com API. You can create as many applications as you want.

{% hint style="info" %}
You might need different applications to differentiate between web apps, mobile apps, or specific devices, if that's relevant to your usage.
{% endhint %}

To create an application:

1. Select Applications from the top navigation menu.
2. Click the Add New Application button.
3. Enter the required values in the "Create an application" form. \
   *Note that you can extend the token duration using the "Application Access Token Expiry Time" field.*
4. Click the Save button.

You will see the "Application created successfully" notification displayed while the browser displays the application management screen.

Your newly created application now appears in the Applications page.

## Step 3: Generate keys

You need a consumer key and consumer secret pair in order to access your application. They are the credentials of the application that is being registered.

<figure><img src="/files/fznbLG9lKphGAnNPqjnr" alt=""><figcaption></figcaption></figure>

To create a new set of keys:

1. Open your application in the Applications page.
2. Select Production Keys from the left navigation pane. As this application is new, the "Key and Secret" section displays that the keys are not generated yet. Let's do that.
3. You do not have to edit the form; just make sure to check the box Client Credentials or/and code according to your use. If you check 'Code', you have to specify the callback URL (see below).
4. Click the Generate Keys button at the bottom of the screen.

<figure><img src="/files/wx0Iig9jrNu9mT0m9iui" alt=""><figcaption></figcaption></figure>

You will see the "Application keys generated successfully" notification displayed. Scroll up to see them appear in the "Key and Secret" section.

<figure><img src="/files/LCKc5D50cSdGloSvfO4a" alt=""><figcaption></figcaption></figure>

You can control the way a client accesses your keys by selecting / deselecting checkboxes in the Grant Types parameter. \
If you are not sure of which Grant Types may best suit your requirements, try selecting all the checkboxes in the Grant Types parameter. You can always come back and uncheck a grant type later if need be.

## Step 4: Create a subscription

You must have your application subscribe to a published API in order to use its endpoints. The subscription process fulfils the authentication process and provides you with access tokens that you can use to invoke the API.

{% hint style="info" %}
A single application can have multiple API subscriptions.
{% endhint %}

To subscribe to an application:

1. Open the applications's "Subscriptions" menu item.
2. Click on "+ Subscribe APIs".&#x20;

   <figure><img src="/files/sdH7lGeWnKbbm48yLHeu" alt=""><figcaption></figcaption></figure>

   This will display a dialog box with predefined APIs.
3. Click on the "Subscribe" button for APIs that are relevant to your requirements.<br>

   <figure><img src="/files/otAOZ4BzXPWjQNNDQ3qj" alt=""><figcaption></figcaption></figure>
4. Close the dialog box when done.

Now the Subscriptions screen displays all your subscriptions attached to that application, indicating which API the subscription refers to.

{% hint style="info" %}
**Deleting subscriptions**\
You can delete a subscription at any given time. \
To do so, click the Delete link at the right of the subscription's row.
{% endhint %}

## Step 5: Generate an access token

The last step consists in creating an OAuth client for the application. The client is automatically created when you generate an application access token

To generate an access token:

1. Go to the "Production Keys" screen.<br>
2. Click the "Generate Access Token" button in the "Key and Secret" section. <br>

   <figure><img src="/files/o30b9L3QT4pFeCWYXqj2" alt=""><figcaption></figcaption></figure>
3. A dialog box appears. Read it thoroughly and click "Generate".<br>

   <figure><img src="/files/F7EYaFMv2OZiKcjaqFFM" alt=""><figcaption></figcaption></figure>
4. Copy the access token and use it in your workflow.<br>

   <figure><img src="/files/MBNJIGqhk7pXwVqNvnSs" alt=""><figcaption></figcaption></figure>

You can now configure your code or toolset to generate API requests.

For instance, here is an example of using [Insomnia](https://insomnia.rest/):&#x20;

<figure><img src="/files/MtETR2eRvTZtLR7tSTYe" alt=""><figcaption></figcaption></figure>

## Sample files

To help you with your API development, find below sample files for both [Insomnia](https://insomnia.rest/) and [Postman](https://www.postman.com/):

{% file src="/files/RHbEm4ixifSOK9oJdVZA" %}

{% file src="/files/ic5Kik7gpG2YAxv9xU7B" %}

## **Done!**

You are now ready to use your API endpoint!

We advise you to first make a test call using your preferred API development tool, such as Postman or Insomnia. We have built the `/ping` endpoint specifically to that end.


# Authentication

The Socios.com API uses the OAuth 2.0 protocol to secure the endpoints that we provide. By using OAuth, developers receive a unique user ID, then use an access token for allowed resources like Polls, Socios.com profile data, etc.

## Obtain your API keys

Once you have obtained your credentials from Socios.com, you must generate the API keys from the developer portal.&#x20;

Follow the steps below:

1. Login to [Socios.com Developer Portal](https://partner-integration.socios.com/devportal/apis).
2. Go to the Applications section, in the top menu bar.&#x20;
3. Open the application for which you want the access tokens.&#x20;
4. Open the OAuth2 Keys page, in the left side bar.

There, you'll find both the consumer key and the consumer secret.

{% hint style="warning" %}
If you don’t already have an application registered in the DevPortal, you have the possibility to create one or more applications. See the [Prerequisites](/partner-api/prerequisites) section for more information.
{% endhint %}

## Choose Your OAuth Flow

You can choose from two OAuth flows:

* **Client Credentials Flow**\
  This is used when your application just needs **read-only access** to public information. Here, a pair of client credentials (`client_id` and `client_secret`) are exchanged for an access token. \
  NOTE: This authentication doesn't include user data.
* **Authorization Code Flow (Socios.com Connect)**\
  This allows your application to **access user's data on their behalf**, but only after obtaining the user's permission. With this flow, an application can acquire more sensitive, opt-in information about a user and interact with the user data.

{% hint style="info" %}
**In short**

If the API endpoint *does not* contain 'user' in the route, you need an access token obtained via the Client Credentials Flow. &#x20;

For instance:

* `GET /polls/{{version}}/polls`
* `GET /polls/{{version}}/poll/{pollId}`

If the API endpoint *does* contain 'user' in the route, you need an access token obtained via the Authorisation Code Flow (Socios.com Connect).

For instance:

* `GET /user/polls`
* `GET /user/poll/{pollId}`
* `POST /user/poll/{pollId}/vote`
  {% endhint %}

## OAuth - Client Credentials Flow

{% hint style="info" %}
**Reminder**\
This flow is used when your application just needs read-only access to public information.
{% endhint %}

### **Step 1: Make your key and secret ready for use**

To prepare your application's consumer key and consumer secret, follow these steps:

1. Concatenate the consumer key, a colon symbol (":"), and the consumer secret into one string.
2. Use [Base64](https://en.wikipedia.org/wiki/Base64) to encode the string you just made. It should look like this: `<Base64(client_id:client_secret)>`

### **Step 2: Get your access token**

Your application needs to ask for access tokens by sending a POST request with the following multipart form data to the token URI: `grant_type=client_credentials` .&#x20;

The application needs to include the encoded key and secret you made in step 1.

This is an example of what the request looks like, using [curl](https://curl.se/):

{% code overflow="wrap" %}

```bash
curl -k -v https://partner.socios.com/oauth2/token
     -d "grant_type=client_credentials" 
     -H "Authorization: Basic cEJ6dUlaaEdwaGZRbWRjVVgwbG5lRmlpdXh3YTo0U0pnV19qTU56aGpIU284OGJuZVhtTnFNMjRh" 
     -H "Content-Type: application/x-www-form-urlencoded" 
```

{% endcode %}

If all goes well, you'll get a response that looks like this:

```json
{
    "token_type":"bearer",
    "access_token":"(a really long string of characters)"
}
```

### **Step 3: Use your access token**

Once you've got your access token, you can use it to ask for information from the API resources. You do this by including it in an authorization header when making HTTPS requests, with the value of Bearer as `<base64 bearer access_token value from step 2>`

Here is an example using curl:

{% code overflow="wrap" %}

```bash
curl --request GET \
  --url https://api-public.socios.com/survey/<apiVersion>/survey/surveys \
  -H 'Authorization: Bearer (a really long string of characters)
```

{% endcode %}

## OAuth - Authorization Code Flow

{% hint style="info" %}
**Reminder**\
This flow allows your application to access user's data on their behalf, but only after obtaining the user's permission.&#x20;
{% endhint %}

To get the user’s permission (and an authorization code), your application will need to direct the user's browser or open a new window to a special web address (URL) with some specific details. \
We advise you to use an [established OAuth2 library](https://oauth.net/code/) for your OAuth client, where you just input your client id, secret, and other details.

If you choose to use an OAuth2 library for your server application, make sure to follow the documentation from the library.\
If you choose to *not* use an OAuth2 library, you can set things up manually by following the following guide...

### Step 1: Redirect users to request access to Socios.com

First of all, go the DevPortal, and open your application's Product Keys page. There, make sure to check the `code` case in the Grant Types section.

<figure><img src="/files/ZxkblWgEK3NollfwiH0T" alt=""><figcaption></figcaption></figure>

You need to send the user to Socios.com to approve access to your application. This is done by creating an authorization URL with the correct details. The following details must always be included:

<table><thead><tr><th width="183.33333333333331">Parameter</th><th width="477">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>response_type</code></td><td>Simply use the word "code".</td><td>Yes </td></tr><tr><td><code>client_id</code></td><td>This is the client ID you got when you set up your application.</td><td>Yes</td></tr><tr><td><code>partner_tag</code></td><td>This is your DevPortal username.</td><td>Yes</td></tr><tr><td><code>redirect_uri</code></td><td>This is the web address in your app where users will be sent after authorisation. It needs to be URL encoded.</td><td>Yes</td></tr></tbody></table>

This is what the authorisation URL might look like:

{% code overflow="wrap" %}

```http
GET https://partner.socios.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL?partner_tag=YOUR_PARTNER_TAG
```

{% endcode %}

For instance, with fake data:

{% code overflow="wrap" %}

```http
GET https://partner.socios.com/oauth2/authorize?response_type=code&client_id=1532**c**63424622b6e9**c**4654e7f97ed40194a1547e114ca1**c**682f44283f39dfa49&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&partner_tag=yourteam
```

{% endcode %}

### Step 2: Socios.com sends users back to your site

Once the user approves your application, Socios.com will send them back to your web address with a temporary code. It might look something like this:

```http
GET https://example.com/oauth/callback?code=TEMPORARY_CODE
```

For instance, with fake data:

{% code overflow="wrap" %}

```http
GET https://example.com/oauth/callback?code=4**c**666b5**c**0**c**0d9d3140f2e0776cbe245f3143011d82b7a2**c**2a590**cc**7e20b79ae8
```

{% endcode %}

### Step 3: Swap the temporary code for an access token

Now that you have the temporary authorisation code, you can swap it for valid access and refresh tokens. You do this by making a POST call to the <https://partner.socios.com/oauth2/token> URL with the following parameters:

<table><thead><tr><th width="183.33333333333331">Parameter</th><th width="416">Description</th></tr></thead><tbody><tr><td><code>grant_type</code></td><td>Value <code>(authorisation code)</code></td></tr><tr><td><code>code</code></td><td>Value from Step 2</td></tr><tr><td><code>client_id</code></td><td>The client ID you received after registering your application.</td></tr><tr><td><code>client_secret</code></td><td>The client secret you received after registering your application.</td></tr><tr><td><code>redirect_uri</code></td><td>The client secret you received after registering your application.</td></tr></tbody></table>

Note: All parameters are mandatory

* `grant_type`: Use `authorization_code.`
* `code`: Use the value from step 2.
* `client_id`: The client ID you received after registering your application.
* `client_secret`: The client secret you received after registering your application.
* `redirect_uri`: The same redirect\_uri used when obtaining the authorisation.

The call would take this shape with curl, for instance:

{% code overflow="wrap" %}

```bash
curl https://partner.socios.com/oauth2/token
     -X POST
     -d 'grant_type=authorization_code&code=TEMPORARY_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=YOUR_REDIRECT_URL'

```

{% endcode %}

For instance, with fake data:

{% code overflow="wrap" %}

```bash
curl https://partner.socios.com/oauth2/token
  -X POST
  -d 'grant_type=authorization_code&code=4c666b5c0c0d9d3140f2e0776cbe245f3143011d82b7a2c2a590cc7e20b79ae8&client_id=1532c63424622b6e9c4654e7f97ed40194a1547e114ca1c682f44283f39dfa49&client_secret=3a21f08c585df35c14c0c43b832640b29a3a3a18e5c54d5401f08c87c8be0b20&redirect_uri=https://example.com/oauth/callback'
```

{% endcode %}

And here's the JSON data you would get back:

After a successful request, you will receive a valid access token:

```json
{
    "access_token": "ACCESS_TOKEN",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN"
}
```

For instance, with fake data:

{% code overflow="wrap" %}

```json
{
    "access_token": "6915ab99857fec1e6f2f6c078583756d0c09d7207750baea28dfbc3d4b0f2cb80",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "73a3431906de603504c1e8437709b0f47d07bed11981fe61b522278a81a9232b7"
}
```

{% endcode %}

### Step 4: Call the API

Once you have a valid access token, you're ready to make your first API call.&#x20;

Here's an example using curl:

```bash
curl https://api-public.socios.com/user/1.0.0/user/me 
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

The expected JSON response would look like this:

```json
{
    "data":
    "userId": "USER_ID"
}
```

For example, with fake data:

```json
{
  "data": {
    "userId": "b87450af-e752-4c61-8e66-65f129297b10"
  }
}
```

You can of course make an API call from any tool, such as [Postman](https://www.postman.com/):

<figure><img src="/files/ifO06U2WKEG2Ry6k7DmZ" alt=""><figcaption></figcaption></figure>

And that's it! Your app is now authenticated using OAuth 2.0 in a user context, without using an OAuth2 library.

## Generate a new access token and refresh token

You might want to create a new set of tokens, for security reasons or just to maintain the integrity of the authentication process. Here is how.

Use the following commands:

{% code overflow="wrap" %}

```bash
curl https://partner.socios.com/oauth2/token
     -X POST
     -d 'grant_type=refresh_token&refresh_token=<refresh-token>'
```

{% endcode %}

Replace the `<refresh-token>` value with the refresh token generated in the previous step.

The expected JSON response would look like this:

```json
{
    "scope":"default",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"7ed6bae2b1d36c041787e8c8e2d6cbf8",
    "access_token":"b7882d23f1f8257f4bc6cf4a20633ab1"
}
```

Expiration example :

* Refresh Token Expiry Time : 90d (7776000) &#x20;
* Access token : 24h (86400)

<figure><img src="/files/Otubj93AfdL5Dr0436BT" alt=""><figcaption></figcaption></figure>

## Revoke an access token

You might want to stop your application from accessing a user's account, or to include a log-out feature in your application. You can do this by revoking the relevant access token.

To revoke an access token, you'll need to send a POST request. The request should include the access token you want to revoke and your application's encode consumer key and consumer secret.

You can revoke access manually, or include it as part of a log out feature.

Here's an example of how you do it using curl:

{% code overflow="wrap" %}

```bash
curl -k -v 
     -d "token=<ACCESS_TOKEN_TO_BE_REVOKED>" 
     -H "Authorization: Basic <base64 encoded (consumerKey:consumerSecret)>" 
     -H "Content-Type: application/x-www-form-urlencoded" 
     https://partner.socios.com/oauth2/revoke
```

{% endcode %}

{% hint style="info" %}
You will receive a `200 OK` for both successful and unsuccessful requests.
{% endhint %}

## Adding tracking parameters

For the purpose of tracking, you can add the following parameters to the URL:

| Parameter  | Description                                                                   |
| ---------- | ----------------------------------------------------------------------------- |
| `referrer` | Name of the third party                                                       |
| `campaign` | <p>ID of the campaign from the marketing tool<br><em>Can be empty</em></p>    |
| `param1`   | The platform where our campaign is located (website / mobile / display, etc.) |
| `param2`   | The page where our campaign is located (homePage, matchPage, etc.)            |
| `param3`   | The type of integration (banner / iframe / API)                               |

By setting these parameters properly, we can share conversion data with you, please make sure to review it with people from Chiliz/Socios to make sure it makes sense.


# API Reference

This documentation provides an overview of all the available endpoints and a walkthrough about how to use them effectively.


# Data API

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="success" %}
Note: The Data API is not changed in the 2025 API Update.
{% endhint %}

## Socios.com Data API

The Data API aims to provide optional information you may need for filtering, naming, translating, categorising, and so on. With the help of Data API, you will be able to retrieve all leagues, sports, and countries handled in the Socios.com environment.&#x20;

In addition, you can retrieve the list of all the available leagues handled by Socios.com and their respective IDs. You can further use it to filter out other endpoints as well.&#x20;

## Using the Data API&#x20;

{% hint style="info" %}
If you're a new user and do not have access to the Socios.com portal yet, see [Prerequisites](/partner-api/prerequisites).
{% endhint %}

1. Once you've logged in to the Socios.com API portal, select **Data**.

<figure><img src="/files/Zxx95sPU4K34Bzy2dSuG" alt=""><figcaption></figcaption></figure>

2. Click the **Try Out** button next to the API URL.

<figure><img src="/files/LmcuINnaVVucYEl8FnM4" alt=""><figcaption></figcaption></figure>

3. You'll see the following modal, indicating registering steps completed. \
   Click the **Try Out** button.

![](/files/Ya0IjrVKsmZrS0efOohp)

4. On the **Security** page that is now displayed, *OAuth* is already selected. Click on the **Get Test Key** button.&#x20;

<figure><img src="/files/aU6b5BnvxXwxAKTTKkke" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You can either use the existing Access token or generate a new Test Key.
{% endhint %}

5. Once the test key is generated, you can display it using the <img src="/files/nuLCGNpRueZTBTcJ5C8p" alt="" data-size="line"> icon.&#x20;

<figure><img src="/files/4XJBNsHrSU1hMkqvTJyS" alt=""><figcaption></figcaption></figure>

## Subscription

1. On the **Subscriptions** page then click on the **SUBSCRIPTION & KEY GENERATION WIZARD** button.

<figure><img src="/files/hf3QoqQpBNAjLHVMjdXW" alt=""><figcaption></figcaption></figure>

2. Then, enter valid details in the **Create application** form fields:

<figure><img src="/files/tAxmPfPIhISUiMW9bplw" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="374">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Application Name</td><td>A valid name of the application</td></tr><tr><td>Shared Quota for Application Tokens</td><td>The amount of tokens generated for each application</td></tr><tr><td>Application Description </td><td>(Optional). A brief description about the application</td></tr></tbody></table>

3. In the *Subscribe to new application* step, enter the **Application** name you want to use. \
   Select a *Business Plan* from the dropdown menu, and click **Next.**

<figure><img src="/files/rvffLZarB3ImGz86emFG" alt=""><figcaption></figcaption></figure>

4. On the *Generate Keys* tab, once you've carefully reviewed the page, select **NEXT**.

<figure><img src="/files/DhB2DThBiOSrNLWJyv7d" alt=""><figcaption></figcaption></figure>

5. On the *Generate Access Token* tab, enter a valid description in the **Scopes** field. Select **NEXT**.

<figure><img src="/files/WRH2XU7TUkD1qFSQdjEu" alt=""><figcaption></figcaption></figure>

6. On the *Copy Access Token* tab, select ![](/files/do6Nr2OBg9rulYnBUQ3g) to copy the Access Token. Once copied, click **FINISH.**

<figure><img src="/files/AVDVScIljUrIMNobhSQy" alt=""><figcaption></figcaption></figure>

7. You can view your newly created subscription under the **Subscriptions** section.

<figure><img src="/files/tOueVcRRz7m7ybDVIylO" alt=""><figcaption></figcaption></figure>


# Data API endpoints

The latest documentation for endpoints is always on the DevPortal: <https://partner.socios.com/devportal/apis/3c83c678-b83c-47cd-a4ca-b27dcb19d643/test>

{% openapi src="/files/3r7elHEn76d2Gc6LE5bG" path="/countries" method="get" %}
[data.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fl2My1UxS8fgHPVuGYwud%2Fdata.json?alt=media\&token=4a8a6802-6751-4c48-8c98-81897c14e7ab)
{% endopenapi %}

{% openapi src="/files/3r7elHEn76d2Gc6LE5bG" path="/fantokens" method="get" %}
[data.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fl2My1UxS8fgHPVuGYwud%2Fdata.json?alt=media\&token=4a8a6802-6751-4c48-8c98-81897c14e7ab)
{% endopenapi %}

{% openapi src="/files/3r7elHEn76d2Gc6LE5bG" path="/fantokens/rate" method="get" %}
[data.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fl2My1UxS8fgHPVuGYwud%2Fdata.json?alt=media\&token=4a8a6802-6751-4c48-8c98-81897c14e7ab)
{% endopenapi %}

{% openapi src="/files/3r7elHEn76d2Gc6LE5bG" path="/sports" method="get" %}
[data.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fl2My1UxS8fgHPVuGYwud%2Fdata.json?alt=media\&token=4a8a6802-6751-4c48-8c98-81897c14e7ab)
{% endopenapi %}

{% openapi src="/files/3r7elHEn76d2Gc6LE5bG" path="/leagues" method="get" %}
[data.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fl2My1UxS8fgHPVuGYwud%2Fdata.json?alt=media\&token=4a8a6802-6751-4c48-8c98-81897c14e7ab)
{% endopenapi %}


# NFT API

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="danger" %}
**NFT API endpoints that are decommissioned with alternatives**

The following endpoint will soon not be available anymore, and we encourage you to use one of the alternative we suggest here:

* `GET /user/nfts`: Get NFT data for currently logged-in user.
* `GET /nft/{id}`: Get data on a single NFT.

\
**NFT API endpoints that are decommissioned with no alternative**

The following endpoints cannot be easily replaced by an alternative.

* `POST /admin/nft/smart-contract`: Create an NFT smart contract.
* `POST /admin/nft/collectible-definition`: Create an NFT collection.
* `POST /admin/nft/{collectibleId}/asset-upload`: Upload a collection of media.
* `POST /admin/nft/{collectibleDefinition}/mint`: Mint a collection of media.

Sadly, if you do rely on one of these, you will have to remove the feature from your service.
{% endhint %}

## Socios.com NFT API

The NFT API aims to provide all the information about NFTs that are held by the user. You will be able to retrieve the full list of NFTs along with all its details including NFT image, name, collection, date of creation, and owner.

## Using the NFT API&#x20;

{% hint style="info" %}
If you're a new user and do not have access to the Socios.com portal yet, see [Prerequisites](/partner-api/prerequisites).
{% endhint %}

1. Once you've logged in to the Socios.com API portal, select **NFT**.

<figure><img src="/files/lmfndHzEq9J7Wr3t7PTn" alt=""><figcaption></figcaption></figure>

2. Click the **Try Out** button next to the API URL.

<figure><img src="/files/In0RSnjghpDcctZp7wAe" alt=""><figcaption></figcaption></figure>

3. You'll see the following modal, indicating registering steps completed. \
   Click the **Try Out** button.

![](/files/Hn2gfGwM1JzVPSbG2H22)

4. On the **Security** page that is now displayed, *OAuth* is already selected. Click on the **Get Test Key** button.&#x20;

<figure><img src="/files/rk1xKlygBL97F47rfQDN" alt=""><figcaption></figcaption></figure>

5. Once the test key is generated, you can display it using the <img src="/files/nuLCGNpRueZTBTcJ5C8p" alt="" data-size="line"> icon.&#x20;

<figure><img src="/files/4XJBNsHrSU1hMkqvTJyS" alt=""><figcaption></figcaption></figure>

## **Subscription**

1. On the **Subscriptions** page then click on the **SUBSCRIPTION & KEY GENERATION WIZARD** button.

<figure><img src="/files/fDmT0KRlf9R9qjs6lGbC" alt=""><figcaption></figcaption></figure>

2. Then, enter valid details in the **Create application** form fields:

<figure><img src="/files/lERS499souKiEDGOsvpM" alt=""><figcaption></figcaption></figure>

| Parameter                           | Description                                           |
| ----------------------------------- | ----------------------------------------------------- |
| Application Name                    | Enter name of the Application                         |
| Shared Quota for Application Tokens | The amount of tokens generated for each application   |
| Application Description             | (Optional). A brief description about the application |

3. In the *Subscribe to new application* step, enter the **Application** name you want to use. \
   Select a *Business Plan* from the dropdown menu, and click **Next.**

Please note, there may be restrictions on the available plans for now.&#x20;

<figure><img src="/files/ukNepgI9Mlz2VckAL6wg" alt=""><figcaption></figcaption></figure>

4. On the *Generate Keys* tab, once you've carefully reviewed the page, select **NEXT**.

<figure><img src="/files/ed1PqW3uwSIKveXhGirS" alt=""><figcaption></figcaption></figure>

5. On the *Generate Access Token* tab, enter a valid description in the **Scopes** field. Select **NEXT**.

<figure><img src="/files/G0N8AKnGyRIj9fImXCis" alt=""><figcaption></figcaption></figure>

6. On the *Copy Access Token* tab, select ![](/files/do6Nr2OBg9rulYnBUQ3g) to copy the Access Token. Once copied, click **FINISH**.&#x20;

<figure><img src="/files/J8n4HKEQ6r4Im0T7ozBA" alt=""><figcaption></figcaption></figure>

7. You can view your newly created subscription under the **Subscriptions** section.

<figure><img src="/files/ACSHtJ0WOnJBPKjrjiN4" alt=""><figcaption></figcaption></figure>


# NFT API endpoints

The latest documentation for endpoints is always on the DevPortal: \
<https://partner.socios.com/devportal/apis/f59193f0-b4ea-4eb7-83f8-8b1f2858f181/test>

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/user/nfts" method="get" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}

{% hint style="success" %}
:arrow\_down: **ALTERNATIVE: Retrieve User NFT Balance** :arrow\_down:\
The following code will allow you to check how many NFT from a specific collection a user holds.&#x20;
{% endhint %}

<pre class="language-javascript" data-overflow="wrap" data-line-numbers><code class="lang-javascript"><strong>import { abi as erc721ABI } from './ERC721ABI.json';
</strong>async function getNFTBalance() {
  const balance = await client.readContract({
    address: '0xYourNFTAddress', // Replace with the actual NFT contract address
    abi: erc721ABI, // ERC-721 ABI
    functionName: 'balanceOf', // Standard ERC-721 function to get balance
    args: ['0xUserWalletAddress'], // User's address whose NFT balance you want to check
  });
  return balance.toString();
}

// Example usage
getNFTBalance().then(console.log);

</code></pre>

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/nft/{id}" method="get" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}


# NFT minting endpoints

NFT minting is a bit more complex than other endpoints, because it implies to write data directly on-chain.

This means that:&#x20;

* You need a wallet,&#x20;
* You have to pay chain fees (gas),
* You need to know where you want to mint the NFT you will create.

## Glossary

* **Minting**: Writing new things (wallets, smart contracts, tokens) on-chain.
* **Fee**: When you mint something, you create a transaction on the chain, and this generate fees (also called "chain fees", "gas fees" or "transaction fees") for using the services.
* **Wallet**: The blockchain wallet where you funds are stored, and to which your smart contracts are linked.
* **Smart contract**: A standardised piece of code that will be executed on-chain in order to create transactions. In the present case, you will be using our NFT smart contract in order to generate new NFTs.
* **Sender**: Your wallet, where the NFTs are created.
* **Recipient**: The wallet where the NFTs will be minted.

## Prerequisites

1. As with all other Socios.com APIs, you need an access to our API manager. \
   If you are not using any other Socios.com APIs, you can authenticate via the [OAuth - Client Credentials Flow](/partner-api/authentication#oauth-client-credentials-flow).
2. You need to inform us, the Socios.com team, that you want to specifically use the NFT minting feature. This way we can generate a wallet for you in order to store the necessary CHZ to pay the fees and start minting you first NFTs.
3. You need to add funds in your wallet to pay the gas fees.

## Steps to mint an NFT

### 1. Create a smart contract

You have two possibilities here:

* mint a smart contract;
* reuse an already minted smart contract.&#x20;

Usually, for a new collection, we recommend to mint a new smart contract.

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/nfts/smartcontract/{smartContractId}" method="get" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/admin/nft/smart-contract" method="post" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}

### 2. Create a collection

A collection is like a draft of your minting, where you collect all attributes of your futur NFT.

{% hint style="info" %}
Take into consideration that creating a smart contract might take some time (approximately 2-3 minutes). If you try to create a collection before your smart contract is created you will receive the error "the smart contract is not enabled". In this case, just wait and try again after a couple of minutes.
{% endhint %}

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/admin/nft/collectible-definition" method="post" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}

### 3. Upload your asset(s) to the collection

Once the collection is created, you can attach your media asset(s) (images or video)  to it.

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/admin/nft/{collectibleId}/asset-upload" method="post" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}

### 4. Mint the collection

Now that everything is reading, you can mint the collection on your wallet or your user's wallet(s) depending of your needs.

{% openapi src="/files/8sINXolbqj50hEwnOyj3" path="/admin/nft/{collectibleDefinition}/mint" method="put" %}
[NFT.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fsk2wL96s6pcBscmiMgAX%2FNFT.json?alt=media\&token=b5e9cb25-8dc7-4753-8945-2d2178c4fa0c)
{% endopenapi %}


# Ping API

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="success" %}
Note: The Ping API is not changed in the 2025 API Update.
{% endhint %}

## Socios Ping API

Using the Ping API, developers can check if their setup is done appropriately and the endpoint communicates efficiently with the API.

Use the [Quick start](/partner-api/quick-start) for a walkthrough implementation.

{% openapi src="/files/udP3BJinOfsJsjHx6OJh" path="/ping" method="get" %}
[Getting\_started.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FPZcafxK9eTaGmW2BfkM7%2FGetting_started.json?alt=media\&token=38a3495e-c4aa-4f31-920c-423a43b45461)
{% endopenapi %}


# Polls API

A Polls API Manager walkthrough

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="danger" %}
**Polls API endpoints that are decommissioned with alternatives**

The following endpoint will soon not be available anymore, and we encourage you to use one of the alternative we suggest here:

* `GET /polls:` Get a list of polls using search filters.
* `GET /user/poll/{pollId}/vote`: Vote on a poll.

\
**Polls API endpoints that are decommissioned with no alternative**

The following endpoints cannot be easily replaced by an alternative:

* `POST /user/polls`: Get user polls with search filters.
* `POST /user/poll/{pollId}`: Get user response on a poll.
* `POST /user/poll/{pollId}/vote`: Get user response on a poll.
* `POST``/user/polls/history`: Get user polls history.

Sadly, if you do rely on one of these, you will have to remove the feature from your service.
{% endhint %}

## Socios.com Polls API&#x20;

The Polls API aims to provide a list of polls including individual details such as their questions, possible answers, starting dates, and end dates. You can enable your users to vote directly on your website if they hold fan tokens of the team related to that poll.

## Using the Poll API&#x20;

{% hint style="info" %}
If you're a new user and do not have access to the Socios.com portal yet, see [Prerequisites](/partner-api/prerequisites).
{% endhint %}

1. Once you've logged in to the Socios.com API portal, select **Polls**.

<figure><img src="/files/TKtemq28djs95lF6zD7E" alt=""><figcaption></figcaption></figure>

2. Click the **Try Out** button next to the API URL.

<figure><img src="/files/AVbN7YMFxxsC3FV3zulf" alt=""><figcaption></figcaption></figure>

3. You'll see the following modal, indicating registering steps completed. \
   Click the **Try Out** button.

![](/files/j5oFG5A4PRWlCAtALSyp)

4. On the **Security** page that is now displayed, *OAuth* is already selected. Click on the **Get Test Key** button.&#x20;

<figure><img src="/files/TWuK7J2oBlWrzlyzdqRZ" alt=""><figcaption></figcaption></figure>

5. Once the test key is generated, you can display it using the <img src="/files/nuLCGNpRueZTBTcJ5C8p" alt="" data-size="line"> icon.&#x20;

<figure><img src="/files/4XJBNsHrSU1hMkqvTJyS" alt=""><figcaption></figcaption></figure>

## Subscription

1. On the **Subscriptions** page then click on the **SUBSCRIPTION & KEY GENERATION WIZARD** button.

<figure><img src="/files/apN3LqJ6wVAj1WLbWVuK" alt=""><figcaption></figcaption></figure>

2. Then, enter valid details in the **Create application** form fields:

<figure><img src="/files/sIvrUnmvxAVFNpMHlUCo" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="333">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Application Name</td><td>A valid name of the Application</td></tr><tr><td>Shared Quota for Application Tokens</td><td>The amount of tokens generated for each application</td></tr><tr><td>Application Description</td><td>(Optional). A brief description about the application</td></tr></tbody></table>

3. In the *Subscribe to new application* step, enter the **Application** name you want to use. \
   Select a *Business Plan* from the dropdown menu, and click **Next.**

<figure><img src="/files/Gfxx5P2CV2pMFKrZ0AXJ" alt=""><figcaption></figcaption></figure>

4. On the *Generate Keys* tab, once you've carefully reviewed the page, select **NEXT**.

<figure><img src="/files/16GUcTApADqVk5yLAEcY" alt=""><figcaption></figcaption></figure>

5. On the *Generate Access Token* tab, enter a valid description in the **Scopes** field. Select **NEXT**.

<figure><img src="/files/BOhGM24rUUMctaK4tqKZ" alt=""><figcaption></figcaption></figure>

6. On the *Copy Access Token* tab, select ![](/files/do6Nr2OBg9rulYnBUQ3g) to copy the Access Token. Once copied, click **FINISH**.&#x20;

   <figure><img src="/files/XknJtOC0LOaNqhwbShpf" alt=""><figcaption></figcaption></figure>

7. You can view your newly created Polls subscription under the **Subscriptions** section.

<figure><img src="/files/50YpBAGbTs83WiNttY5f" alt=""><figcaption></figcaption></figure>


# Polls API endpoints

The latest documentation for endpoint is always on the DevPortal: \
<https://partner.socios.com/devportal/apis/d93ca9b9-6e1f-4ec7-813e-a4e8c3c1d658/test>

{% openapi src="/files/Sjgt1g6TWcWhAHsAEnO3" path="/polls" method="get" %}
[Polls.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fc4oidA5xBonCIsDYQArk%2FPolls.json?alt=media\&token=ef654fa4-42f8-4b36-9884-fdacf9eacf63)
{% endopenapi %}

{% hint style="danger" %}
REMOVED WITH NO ALTERNATIVE AVAILABLE
{% endhint %}

{% openapi src="/files/Sjgt1g6TWcWhAHsAEnO3" path="/poll/{pollId}" method="get" %}
[Polls.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fc4oidA5xBonCIsDYQArk%2FPolls.json?alt=media\&token=ef654fa4-42f8-4b36-9884-fdacf9eacf63)
{% endopenapi %}

{% openapi src="/files/Sjgt1g6TWcWhAHsAEnO3" path="/user/poll/{pollId}/vote" method="post" %}
[Polls.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fc4oidA5xBonCIsDYQArk%2FPolls.json?alt=media\&token=ef654fa4-42f8-4b36-9884-fdacf9eacf63)
{% endopenapi %}

{% hint style="success" %}
:arrow\_down: **ALTERNATIVE: Allow a user to vote on a specific poll** :arrow\_down:
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```javascript
import { createWalletClient, privateKeyToAccount } from 'viem';

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);

const walletClient = createWalletClient({
  account,
  transport: http('https://rpc.ankr.com/chiliz'),
});

async function vote(id, weight) {
  const txHash = await walletClient.writeContract({
    address: '0xPollAddress', // Replace with the poll contract address
    abi: survey3ABI, // Poll contract ABI
    functionName: 'vote', // Function to cast the vote
    args: [id, BigInt(weight)], // Replace 'id' with answer id and 'weight' with the amount of tokens that should be used to cast the vote
  });
  return txHash;
}

// Example usage
vote('dab3d446-959f-47e7-8789-f618d969de1e', 1).then(console.log);
```

{% endcode %}

{% openapi src="/files/Sjgt1g6TWcWhAHsAEnO3" path="/user/poll/{pollId}" method="get" %}
[Polls.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fc4oidA5xBonCIsDYQArk%2FPolls.json?alt=media\&token=ef654fa4-42f8-4b36-9884-fdacf9eacf63)
{% endopenapi %}

{% hint style="success" %}
:arrow\_down: **ALTERNATIVE: Retrieve user vote on a specific poll** :arrow\_down:
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```javascript
import { createPublicClient, http, keccak256 } from 'viem';
import { abi as survey3ABI } from './Survey3ABI.json';

const client = createPublicClient({
  transport: http('https://rpc.ankr.com/chiliz'),
});

const pollAddress = '0xPollAddress'; // Replace with the actual poll contract address
const userAddress = '0xUserAddress'; // Replace with the user's wallet address

// Returns hashes of answerIds that the user voted on
async function getUserVoteHashes() {
  const votes = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getUserAnswers', // Function to retrieve the answers that the user voted on
    args: [userAddress], // User's address whose votes you want to fetch
  });
  return votes;
}

// Returns votes in plain text
async function getUserVotesPlainText() {
  // fetch all answers
  const answers = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getAnswers', // Function to retrieve the answers
    args: [], // User's address whose votes you want to fetch
  });

  // fetch user's votes
  const votes = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getUserAnswers', // Function to retrieve the answers that the user voted on
    args: [userAddress], // User's address whose votes you want to fetch
  });

  // filter answers, return the ones that the user voted on
  const plainTextVotes = answers.filter(a => votes.includes(keccak256(a.id)));

  return plainTextVotes;
}

// Example usage
getUserVotesPlainText().then(console.log);
getUserVoteHashes().then(console.log);
```

{% endcode %}

{% openapi src="/files/Sjgt1g6TWcWhAHsAEnO3" path="/user/polls" method="get" %}
[Polls.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fc4oidA5xBonCIsDYQArk%2FPolls.json?alt=media\&token=ef654fa4-42f8-4b36-9884-fdacf9eacf63)
{% endopenapi %}

{% hint style="danger" %}
REMOVED WITH NO ALTERNATIVE AVAILABLE
{% endhint %}

{% openapi src="/files/Sjgt1g6TWcWhAHsAEnO3" path="/user/polls/history" method="get" %}
[Polls.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2Fc4oidA5xBonCIsDYQArk%2FPolls.json?alt=media\&token=ef654fa4-42f8-4b36-9884-fdacf9eacf63)
{% endopenapi %}

{% hint style="danger" %}
REMOVED WITH NO ALTERNATIVE AVAILABLE
{% endhint %}


# Rewards API

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="success" %}
Note: The Rewards API is not changed in the 2025 API Update.
{% endhint %}

## Socios.com Rewards API

The Rewards API aims to provide all information related to the rewards that clubs provide to their most engaged fans.

## Using the Rewards API

{% hint style="info" %}
If you're a new user and do not have access to the Socios.com portal yet, see [Prerequisites](/partner-api/prerequisites).
{% endhint %}

1. Once you've logged in to the Socios.com API portal, select **Rewards**.
2. Click the **Try Out** button next to the API URL.
3. You'll see the following modal, indicating the registration steps that are completed. \
   Click the **Try Out** button.\
   ![](/files/48cBZUo3aRSK4XI2xtG3)
4. On the **Security** page that is now displayed, *OAuth* is already selected. Click on the **Get Test Key** button.&#x20;
5. Once the test key is generated, you can display it using the <img src="/files/nuLCGNpRueZTBTcJ5C8p" alt="" data-size="line"> icon.&#x20;

## Subscription

1. On the **Subscriptions** page, click on the **SUBSCRIPTION & KEY GENERATION WIZARD** button.
2. Then, enter valid details in the **Create application** form fields:<br>

   <table><thead><tr><th width="374">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Application Name</td><td>A valid name of the application.</td></tr><tr><td>Shared Quota for Application Tokens</td><td>The amount of tokens generated for each application.</td></tr><tr><td>Application Description </td><td>Optional. A brief description about the application.</td></tr></tbody></table>
3. In the *Subscribe to new application* step, enter the **Application** name you want to use. \
   Select a *Business Plan* from the dropdown menu, and click **Next.**
4. On the *Generate Keys* tab, once you've carefully reviewed the page, select **NEXT**.
5. On the *Generate Access Token* tab, enter a valid description in the **Scopes** field. Select **NEXT**.
6. On the *Copy Access Token* tab, select ![](/files/do6Nr2OBg9rulYnBUQ3g) to copy the Access Token. Once copied, click **FINISH.**
7. You can view your newly created subscription under the **Subscriptions** section.


# Rewards API endpoints

{% openapi src="/files/nnCFb3mdIIDdaPHQPSpp" path="/rewards" method="get" %}
[rewards.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FksrBi6llCjVr46QsWwVX%2Frewards.json?alt=media\&token=f692949f-ddc1-4eb6-ad1e-a11dad907231)
{% endopenapi %}

{% openapi src="/files/nnCFb3mdIIDdaPHQPSpp" path="/reward-categories" method="get" %}
[rewards.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FksrBi6llCjVr46QsWwVX%2Frewards.json?alt=media\&token=f692949f-ddc1-4eb6-ad1e-a11dad907231)
{% endopenapi %}

{% openapi src="/files/nnCFb3mdIIDdaPHQPSpp" path="/rewards/{rewardId}" method="get" %}
[rewards.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FksrBi6llCjVr46QsWwVX%2Frewards.json?alt=media\&token=f692949f-ddc1-4eb6-ad1e-a11dad907231)
{% endopenapi %}


# User API

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="success" %}
Note: The User API is not changed in the 2025 API Update.
{% endhint %}

## Socios.com User API

The User API aims to provide all information needed to identify your users and adapt your interfaces according to their information such as user name, avatar, mobile number, and email.

## Using the User API

{% hint style="info" %}
If you're a new user and do not have access to the Socios.com portal yet, see [Prerequisites](/partner-api/prerequisites).
{% endhint %}

1. Once you've logged in to the Socios.com API portal, select **User**.

<figure><img src="/files/CoK2pM3uLInon09oX0SE" alt=""><figcaption></figcaption></figure>

2. Click the **Try Out** button next to the API URL.

<figure><img src="/files/YWiwKyohwegPdL5evihN" alt=""><figcaption></figcaption></figure>

3. You'll see the following modal, indicating registering steps completed. \
   Click the **Try Out** button.

![](/files/48cBZUo3aRSK4XI2xtG3)

4. On the **Security** page that is now displayed, *OAuth* is already selected. Click on the **Get Test Key** button.&#x20;

<figure><img src="/files/iiFVyQGcV4G1hZGrasAE" alt=""><figcaption></figcaption></figure>

5. Once the test key is generated, you can display it using the <img src="/files/nuLCGNpRueZTBTcJ5C8p" alt="" data-size="line"> icon.&#x20;

<figure><img src="/files/4XJBNsHrSU1hMkqvTJyS" alt=""><figcaption></figcaption></figure>

## Subscription

1. On the **Subscriptions** page then click on the **SUBSCRIPTION & KEY GENERATION WIZARD** button.

<figure><img src="/files/LJm0XXxHrv45xyBNbWOp" alt=""><figcaption></figcaption></figure>

2. Then, enter valid details in the **Create application** form fields:

<figure><img src="/files/mxFHMVVMcESBXKTU4AoJ" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="350">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Application Name</td><td>A desired application name</td></tr><tr><td>Shared Quota for Application Tokens</td><td>The amount of tokens generated for each application</td></tr><tr><td>Application Description</td><td>(Optional). A brief description about the application</td></tr></tbody></table>

3. In the *Subscribe to new application* step, enter the **Application** name you want to use. \
   Select a *Business Plan* from the dropdown menu, and click **Next.**

<figure><img src="/files/3qwVjWI0EIJSCROKrZdK" alt=""><figcaption></figcaption></figure>

4. On the *Generate Keys* tab, once you've carefully reviewed the page, select **NEXT**.

<figure><img src="/files/yeWVR50Lzu3toriMYawg" alt=""><figcaption></figcaption></figure>

5. On the *Generate Access Token* tab, enter a valid description in the **Scopes** field. Select **NEXT**.

<figure><img src="/files/DpDBSdjTP1kCsZEJ4ifI" alt=""><figcaption></figcaption></figure>

6. On the *Copy Access Token* tab, select ![](/files/do6Nr2OBg9rulYnBUQ3g) to copy the Access Token. Once copied, click **FINISH**.&#x20;

<figure><img src="/files/5sS2ALtsxnGIVDM9hQZs" alt=""><figcaption></figcaption></figure>

7. You can view your newly created subscription under the **Subscriptions** section.

<figure><img src="/files/ZvrsIvTfigdTdg7goFMc" alt=""><figcaption></figcaption></figure>


# User API endpoints

The latest documentation for endpoints is always on the DevPortal: <https://partner.socios.com/devportal/apis/682c4c5a-dab5-4793-a82f-134aac530844/test>

{% openapi src="/files/sTpwuakJi3Cb1bASUW5I" path="/user/me" method="get" %}
[User.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2F62uxd44q8Z0tSQ0kkKQM%2FUser.json?alt=media\&token=a6ca2a38-1072-4c4a-928e-c475cd9aced6)
{% endopenapi %}


# Wallet API

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="danger" %}
**Wallet API endpoints that are decommissioned with alternatives**

The following endpoints will soon not be available anymore, and we encourage you to use one of the alternative we suggest here:

* `GET /user/wallet`:  Get wallet data for currently logged-in user.
* `GET /user/wallet/{transactionId}`: Get the transactions of a user wallet.
* `GET /user/wallet/transaction-history/fan-token:` Get the transaction history of a user wallet
* `POST /admin/wallet/transfer/fan-token`: Transfer Fan Tokens.

**Polls API endpoints that are decommissioned with no alternative**

The following endpoints cannot be easily replaced by an alternative:

* `POST /wallet/sign-message`:&#x20;

Sadly, if you do rely on one of these, you will have to remove the feature from your service.
{% endhint %}

## Socios.com Wallet API

The Wallet API aims to provide all information related to the wallet of the logged-in user, starting with how many Chiliz she/he owns.

In addition, you can use the Wallet API to redeem vouchers.

## Using the Wallet API

{% hint style="info" %}
If you're a new user and do not have access to the Socios.com portal yet, see [Prerequisites](/partner-api/prerequisites).
{% endhint %}

1. Once you've logged in to the Socios.com API portal, select **Wallet**.
2. Click the **Try Out** button next to the API URL.
3. You'll see the following modal, indicating registering steps completed. \
   Click the **Try Out** button.\
   ![](/files/48cBZUo3aRSK4XI2xtG3)
4. On the **Security** page that is now displayed, *OAuth* is already selected. Click on the **Get Test Key** button.&#x20;
5. Once the test key is generated, you can display it using the <img src="/files/nuLCGNpRueZTBTcJ5C8p" alt="" data-size="line"> icon.&#x20;

## Subscription

1. On the **Subscriptions** page then click on the **SUBSCRIPTION & KEY GENERATION WIZARD** button.
2. Then, enter valid details in the **Create application** form fields:<br>

   <table><thead><tr><th width="374">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Application Name</td><td>A valid name of the application</td></tr><tr><td>Shared Quota for Application Tokens</td><td>The amount of tokens generated for each application</td></tr><tr><td>Application Description </td><td>(Optional). A brief description about the application</td></tr></tbody></table>
3. In the *Subscribe to new application* step, enter the **Application** name you want to use. \
   Select a *Business Plan* from the dropdown menu, and click **Next.**
4. On the *Generate Keys* tab, once you've carefully reviewed the page, select **NEXT**.
5. On the *Generate Access Token* tab, enter a valid description in the **Scopes** field. Select **NEXT**.
6. On the *Copy Access Token* tab, select ![](/files/do6Nr2OBg9rulYnBUQ3g) to copy the Access Token. Once copied, click **FINISH.**
7. You can view your newly created subscription under the **Subscriptions** section.

## Live example

See how [FanMarketCap](https://www.fanmarketcap.com/) uses the Wallet API to retrieve and display all the tokens in a user's wallet, along with NFTs:

<figure><img src="/files/i5j4p1b2mcFTjGQLWxlc" alt=""><figcaption></figcaption></figure>

You can create a FanMarketCap account for free, to see how it behaves with your one Socios.com account!


# Wallet API endpoints

The latest documentation for endpoints is always on the DevPortal: <https://partner.socios.com/devportal/apis/1464738d-213b-4073-8599-46b63390a6ea/test>

{% openapi src="/files/Eia5oxOIBgs21VRUDy1V" path="/user/wallet" method="get" %}
[wallet.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FnT5LAJN0Iy67xpww39w5%2Fwallet.json?alt=media\&token=33d0368b-03ab-4e83-908c-63844a36d734)
{% endopenapi %}

{% hint style="success" %}
:arrow\_down: **ALTERNATIVE: Retrieve User Token Balance** :arrow\_down:<br>
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```javascript
import { createPublicClient, http } from 'viem';
import { abi as erc20ABI } from './ERC20ABI.json';

const client = createPublicClient({
  transport: http('https://rpc.ankr.com/chiliz'),
});

const tokenAddress = '0xYourTokenAddress'; // Replace with the actual ERC-20 contract address
const userAddress = '0xUserWalletAddress'; // Replace with the user's wallet address
async function getTokenBalance() {
  const balance = await client.readContract({
    address: tokenAddress, // Contract address of the token
    abi: erc20ABI, // ERC-20 ABI
    functionName: 'balanceOf', // Standard ERC-20 function to get balance
    args: [userAddress], // User's address whose balance you want to check
  });
  return balance.toString();
}
// Example usage
getTokenBalance().then(console.log);
```

{% endcode %}

{% openapi src="/files/Eia5oxOIBgs21VRUDy1V" path="/user/wallet/sign-message" method="post" %}
[wallet.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FnT5LAJN0Iy67xpww39w5%2Fwallet.json?alt=media\&token=33d0368b-03ab-4e83-908c-63844a36d734)
{% endopenapi %}

{% hint style="danger" %}
REMOVED WITH NO ALTERNATIVE AVAILABLE
{% endhint %}

{% openapi src="/files/Eia5oxOIBgs21VRUDy1V" path="/user/wallet/{transactionId}" method="get" %}
[wallet.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FnT5LAJN0Iy67xpww39w5%2Fwallet.json?alt=media\&token=33d0368b-03ab-4e83-908c-63844a36d734)
{% endopenapi %}

{% hint style="success" %}
:arrow\_down: **ALTERNATIVE: Retrieve a User's Transaction** :arrow\_down:
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```javascript
async function getTransaction(txHash) {
  const transaction = await client.getTransaction({
    hash: txHash, // Replace with the actual transaction hash
  });
  return transaction;
}

// Example usage
getTransaction('0xTransactionHash').then(console.log);
```

{% endcode %}

{% openapi src="/files/Eia5oxOIBgs21VRUDy1V" path="/user/wallet/transaction-history/fan-token" method="get" %}
[wallet.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FnT5LAJN0Iy67xpww39w5%2Fwallet.json?alt=media\&token=33d0368b-03ab-4e83-908c-63844a36d734)
{% endopenapi %}

{% openapi src="/files/Eia5oxOIBgs21VRUDy1V" path="/admin/wallet/transfer/fan-token" method="post" %}
[wallet.json](https://31329255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMDcaoJLMj5Y3jzFMTONF%2Fuploads%2FnT5LAJN0Iy67xpww39w5%2Fwallet.json?alt=media\&token=33d0368b-03ab-4e83-908c-63844a36d734)
{% endopenapi %}

{% hint style="success" %}
:arrow\_down: **ALTERNATIVE: Send ERC-20 Tokens to a User Wallet** :arrow\_down:
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```javascript
import { createWalletClient, privateKeyToAccount } from 'viem';

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);
const walletClient = createWalletClient({
  account,
  transport: http('https://rpc.ankr.com/chiliz'),
});
async function sendTokens(to, amount) {
  const txHash = await walletClient.writeContract({
    address: '0xYourTokenAddress', // Replace with the ERC-20 token contract address
    abi: erc20ABI, // ERC-20 ABI
    functionName: 'transfer', // Standard ERC-20 function to transfer tokens
    args: [to, BigInt(amount * 1e18)], // Replace 'to' with recipient address and 'amount' with the amount to send
  });
  return txHash;
}
// Example usage
sendTokens('0xRecipientAddress', 10).then(console.log);

```

{% endcode %}


# Login button

{% hint style="warning" %}
In Q1 2025, the Chiliz team will decommission several endpoints and features. This is to ensure that the Socios.com API remains focused on the Socios.com app features, and to bring it always closer to the Web3 ecosystem.&#x20;

Don't worry! We will provide you with alternatives right here on this documentation site.

You will find more information [in this guide](/partner-api/2025-api-update-overview), and in each API section of this site.
{% endhint %}

{% hint style="danger" %}
As part of the 2025 API Update, the Login button is decommissioned in favor of building your own wallet integration. [See this documentation](https://docs.chiliz.com/develop/advanced/how-to-integrate-socios-wallet-in-your-dapp).
{% endhint %}

## Description

Partner applications can use the Socios.com login button to allow their users to log into their Socios.com account from a third-party environment.&#x20;

Clicking on this button opens the Socios.com Connect login modal (such as any OAuth login system such as Google's, Facebook's, etc.) which in turn allows the third-party application to access Socios.com user data on the user's behalf.

## Sample button

{% hint style="info" %}
*This example doesn't onboard all the OAuth mechanism, this is only a front-end example.*

*To fully implement it, you will need to dive into the rest of the Partner API documentation, notably the* [Authentication](/partner-api/authentication) part.
{% endhint %}

Here is the official Socios.com login button:

![](/files/uKGHF8XuVPVmzAa02GV0)

And here is the needed CSS code to display it into a partner website:

{% code overflow="wrap" fullWidth="false" %}

```html
<style>
  .sociosComLoginButton {
    background-color: rgb(0, 33, 55);
    box-sizing: border-box;
    color: #fff;
    cursor: pointer;
    border: none;
    border-radius: 8px;
    font-size: 16px;
    padding: 15px 20px;
    white-space: nowrap;
  }

  .sociosComLoginButton:hover {
    background-color: rgb(0, 46, 77);
  }

  .sociosComLoginButton span {
    display: flex;
    align-content: center;
    justify-content: center;
  }

  .sociosComLoginButton img {
    margin-right: 10px;
  }
</style>

<button type="button" class="sociosComLoginButton">
  <span><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABIAAAAUCAYAAACAl21KAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAIbSURBVHgBpVRLbhpBEK0qMJEAybAI3lhJs0giK4hM32C4gXMD5wTGJyA5Ac4JjE9gbgA3GPMLSybrYGUixYlkM12pxgwM4yHK50mt/lT1e1X9KQSB53kqk8u5bIyDQM8ZwbHrwKxggwAQA2T2ATBgMAMD0Idi8VpXqwEOh+O2bGzC/8DAWZYJj0V5rYrAfZl9RqLrpL9ErKQrIeIb2eKuDQStbDGfV99vbyVq6NRrtXfwh/C8qcpkF20GCUTIqVDILw0h8yX8BbQ+8iG2h8rlMvwrQjn8NVFubw8OKk+BEJ00Z2Z2ePv2UkHS/INKBZ4dHp56s1kpQXIinSettxpvIUOkVsPAEi3zLO3vK0cpb4e6XbsQm21rsfDuritXeSnPpxspn/M2WrGoXGmzmM2OXdgFMTYTZFdRdLaX1tkllkamUtRL8TP7nT2NMEp1liYWBN++xsg232swGr0fDMbNxAZ3l9pwPO59md9ERK5ds7cGZpHtAHJLHNqRs/ynPsYeXARvOlX2n81v5nb60fot/dcOw8kJIV8Ig28y1NBH8gWSJJOJQwxXtrw8yeX8Vy9f6EiMIiddf90xwB+sEy3C2Wg0aVn1TfqfTslwb1mjROznj7ARjxgfqcp5EWBrlZ+PDFJOuCSlxX1Ygn54X3irdXUr7UdED2kOj4ky7USFBINwpmu187Q9lLao6/WuuaeGff5RFGaBeheJxS+TpX6sx8ZIugAAAABJRU5ErkJggg==" />Connect with Socios.com</span>
</button>
```

{% endcode %}


# Overview

The Partner Web App is a tailored and scoped version of the Socios.com web app, focusing on content from specific partners.&#x20;

These partner-focused interfaces are activated only after a partnership agreement is in place.&#x20;

The Partner Web App features registration, login, token purchase for the partner's team, voting, and staking, among others.


# Integration

Integrating the Socios.com Partner Web App

You can seamlessly incorporate our Partner Web App into your website.&#x20;

To achieve this, you must use this Partner URL:&#x20;

```url
https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]
```

An example URL would be the one from the Bern football club [BSC Young Boys](https://www.bscyb.ch/):

{% code overflow="wrap" fullWidth="false" %}

```url
https://app.socios.com/partner/5796d2d6-da2a-4914-82fe-3eeaba3c1bca?partnerWebAppId=5796d2d6-da2a-4914-82fe-3eeaba3c1bca
```

{% endcode %}

You can retrieve the `Partner ID` you want by browsing on app.socios.com and looking for the specific partner detailed page. The id will be located after `/partner/` in the URL.

They designed the integration to look like this:

<figure><img src="/files/wECy4dFajqPSeG1yDVGB" alt=""><figcaption></figcaption></figure>

Try it for yourself: <https://ybo.bscyb.ch/>

## Web integration

You can insert the Partner Web App into an iframe for a responsive website.&#x20;

The necessary HTML code is:

{% code overflow="wrap" %}

```html
<iframe src="https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]" width="100%" height="800px" allow="camera 'src'; publickey-credentials-get 'src'"></iframe>
```

{% endcode %}

### **SEO Optimisations**

Here are two ways to improve the findability of your Fan Token page from search engines:

* Fill the `<title>` HTML tag with "\[Partner shortname] Fan Token", so that it  appears clearly in the browser tab. \
  For instance, for Apollon Limassol fan token: `<title>APL Fan Token</title>`
* Make sure to mention this string in the URL of the page. \
  For instance: <https://www.apollon.com.cy/en/apl-fan-token/>

## Mobile integration

For mobile apps, you can create a native WebView using the following URL:

```url
https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]
```

This way the web app will be seamlessly implemented within your mobile app. It can work on both native or hybrid mobile app.

Of course, building a native WebView requires much more work than just using this URL -- starting with the fact that a native implementation will require you to develop it twice (iOS + Android).

See for instance how French rugby club Stade Français did it:

<div><figure><img src="/files/P3bTZYiYaOR6adWN7K6N" alt=""><figcaption></figcaption></figure> <figure><img src="/files/BCh1NLhaOQB2NTZIReig" alt=""><figcaption></figcaption></figure> <figure><img src="/files/cS7KlK9veupDKRwewvBI" alt=""><figcaption></figcaption></figure></div>


# URL parameters

## Adding tracking parameters

For the purpose of tracking, you can add the following parameters to the URL:

| Parameter  | Description                                                                   |
| ---------- | ----------------------------------------------------------------------------- |
| `referrer` | Name of the partner                                                           |
| `campaign` | <p>ID of the campaign from the marketing tool<br><em>Can be empty</em></p>    |
| `param1`   | The platform where our campaign is located (website / mobile / display, etc.) |
| `param2`   | The page where our campaign is located (homePage, matchPage, etc.)            |
| `param3`   | The type of integration (banner / iframe / API)                               |

By setting these parameters properly, we can share conversion data with you.

Incorporating them into the URL, it would resemble this:

<pre class="language-url" data-overflow="wrap"><code class="lang-url"><strong>https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]&#x26;referrer=paris_saint_germain&#x26;campaign=FB_psg_20456&#x26;param1=website&#x26;param2=homePage&#x26;param3=banner
</strong></code></pre>

Separating each parameter to make it more readable:

```sh
https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]
&referrer=paris_saint_germain
&campaign=FB_psg_20456
&param1=website
&param2=homePage
&param3=banner
```

{% hint style="info" %}
The`param1`,`param2` and`param3` parameters can be tailored to a partner's usage, hence the generic names. \
They have an impact on the charts that we create internally, which we can share with you.
{% endhint %}

## Incorporating login/registration information as parameters

To facilitate a better user experience, you can auto-fill the login/registration form by supplying user information: country code, phone number, etc.

This requires a base64-encoded JSON value, which you can provide through the `userInfo` parameter. \
This encoded value may include the following JSON:

```json
{
    "countryCode": "+33",
    "phoneNumber": "0623456789",
    "email": "example@mail.com",
    "username": "username",
    "country": "France",
    "dob": "1970-01-01"
}
```

Incorporating the above base64-encoded JSON within the URL, it would resemble this:

{% code overflow="wrap" %}

```bash
https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]&userInfo=ew0KICAgICJjb3VudHJ5Q29kZSI6ICIrMzMiLA0KICAgICJwaG9uZU51bWJlciI6ICIwNjIzNDU2Nzg5IiwNCiAgICAiZW1haWwiOiAiZXhhbXBsZUBtYWlsLmNvbSIsDQogICAgInVzZXJuYW1lIjogInVzZXJuYW1lIiwNCiAgICAiY291bnRyeSI6ICJGcmFuY2UiLA0KICAgICJkb2IiOiAiMTk5OS0wMS0wMSINCn0%3D
```

{% endcode %}

### Retrieve user session (to avoid multiple logins)

In order to simplify user flow and more especially the login, you can add login\_redirect=true parameter. Having this parameter will check if the user has an active session on Socios.com and avoid to ask him to log in again.

{% code overflow="wrap" %}

```
https://app.socios.com/partner/[PARTNER_ID]?partnerWebAppId=[PARTNER_ID]&login_redirect=true
```

{% endcode %}


# On-Ramp Fan Tokens

Integrating the Socios.com On ramp Fan Token

## Implement the On-Ramp Fan Token flow

Our On-Ramp Fan Token is an extension of the Partner web app. This feature will allow your users to buy the Fan Token of one team.

To integrate it into your website or mobile app, you only need your Partner URL and a few parameters (all [others parameters](/partner-web-app/url-parameters) can be combined with the followings).&#x20;

<pre class="language-url"><code class="lang-url"><strong>https://[Partner Shortname].socios.com/on-ramp-token
</strong></code></pre>

You must use your Partner URL in an iframe, a modal or a WebView.

Then, add a few dedicated parameters:

| Parameter            | Value                                    | Description                                                            |
| -------------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
| `on_ramp_token`      | true                                     | Mandatory. Set it to `true` to trigger the On-Ramp Fan Token flow.     |
| `purchase_qty`       | 0 -> infinite                            | Optional. User will be able to change it when they arrive on the flow. |
| `fiat_currency_code` | 'EUR', 'USD', 'GBP', 'BRL', 'TRY', 'KRW' | Optional.                                                              |

For instance, ACM would have the following URL to redirect to the ACM On-Ramp Fan Token flow with 34 pre-populated ACM tokens to buy and with USD FIAT currency

{% code overflow="wrap" %}

```
https://acm.socios.com/on-ramp-token?purchase_qty=10&on_ramp_token=true&fiat_currency_code=EUR
```

{% endcode %}

## Get informed once the user has finalised their transaction

The window that triggers the On-Ramp flow can listen to the `message` event from a `postMessage` and the `onRampTokenPaymentStatus` code, in order to retrieve when the user has finalised their transaction, and to see how many fan tokens they have bought. &#x20;

{% hint style="info" %}
We strongly recommend to check your transfer via RPC data (ie. token balance).\
See [Working with Tokens](/interact-with-chiliz-chain/working-with-tokens#retrieve-user-token-balances)
{% endhint %}

Here is how you should handle it, making sure you are listening to the right `event.data` and the right `event.origin`:

```javascript
window.addEventListener(
  "message",
  (event) => {
    if (
      event.data !== "onRampTokenPaymentStatus" ||
      event.origin !== "https://gateway-capsicum.socios.com"
    )
      return;

    <HERE do a refetch or whatever is needed>
  },
  false
); 
```