Setup API Portal
Setup smart contract API portal
Summary
To set up the API portal for a smart contract, you first need to compile the contract and locate its ABI file. The ABI is auto-generated during compilation and acts as a translation layer between your contract and external tools like frontends or API layers. You'll find this ABI in the artifacts/contracts/ContractName.sol/ContractName.json file if you used Hardhat, or under out/ if you used Foundry. This file contains structured definitions of all contract functions and events, and is essential for enabling external calls through REST or GraphQL.
Once you have the ABI file, navigate to your application on the SettleMint platform and go to the middleware section. Here, you'll need to add a new middleware of type API portal. You will assign a name, select the blockchain node where your contract is deployed, and upload the ABI file. Make sure the ABI file is named appropriately because that name will reflect in your API structure. After confirming the setup, the API portal will automatically expose both REST and GraphQL endpoints based on your contract's ABI.
To connect the API portal with your contract logic, you must provide the smart contract's deployed address. This can be found inside the deployed_addresses.json file generated by Ignition after a successful deployment. The portal will use this address to direct requests to the correct contract instance.
Once deployed, you can start making REST API calls using standard HTTP requests. You'll use the base URL shown under the portal's connect tab, and structure your API requests according to the contract's ABI. Each call should include authentication via your application access token, and a JSON payload specifying the function name, parameters, and caller details such as from, gasLimit, and simulate. The response will return transaction hashes for writes, or data for reads.
How to setup API portal in SettleMint platform
1. Understanding application binary interface (ABI)
The application binary interface (ABI) is an essential artifact in Ethereum and other EVM-based blockchain ecosystems that defines how smart contracts communicate with the outside world. It acts as a formal agreement between a deployed smart contract and any external entity, such as web applications, backend servers, wallets, or command-line tools, about how to encode and decode data for function calls, returns, and events. The ABI describes, in a structured JSON format, each function's name, inputs, outputs, type (e.g., function, constructor, event), and visibility (view, pure, payable, etc.).
The ABI is generated automatically when a Solidity smart contract is compiled. When developers write a Solidity contract and run it through the Solidity compiler (solc), or through development frameworks like Hardhat or Truffle, the output includes several artifacts, one of which is the ABI. This ABI is derived by analyzing the contract's function signatures, input and output types, event declarations, and constructor. For each function, the compiler calculates a unique function selector, a 4-byte identifier based on the first 4 bytes of the keccak256 hash of the function's signature (e.g., transfer(address,uint256)). The ABI then maps these selectors to their corresponding human-readable definitions in JSON form.
At runtime, when an application (like a frontend built with Web3.js or Ethers.js) wants to interact with the contract, it uses this ABI to encode the function call and its parameters into hexadecimal data that the Ethereum Virtual Machine (EVM) can understand. Similarly, when the EVM returns data (e.g., the result of a view function or an event emitted during a transaction), the ABI provides the blueprint for decoding this binary data back into usable JavaScript objects. In addition to function calls, the ABI is also critical for subscribing to and decoding events emitted by the contract. Each event in the contract is represented in the ABI with a structure that allows applications to listen for specific logs on-chain and parse them into structured data.
2. Using ABI from the UserData.sol smart contract which we deployed in the previous step
Navigate to /artifacts/contracts/UserData.sol/UserData.json to find the ABI of the contract we compiled and deployed in the previous step. Download the JSON file.
If you build using Foundry, you will find the ABI in the out folder out>ContractName.sol>ContractName.json
The ABI you will get is the following-
In this ABI, we have a set of functions, inputs, outputs, and events captured from the UserData.sol smart contract. It outlines how external applications can interact with the contract by providing structured definitions for each callable function and emitted event.
UserData contract ABI summary
| Events | Indexed Params | Non-Indexed Params |
|---|---|---|
ProfileCreated | userId (uint256) | name (string), email (string), age (uint8), country (string), isKYCApproved (bool) |
ProfileUpdated | userId (uint256) | name (string), email (string), age (uint8), country (string), isKYCApproved (bool) |
ProfileDeleted | userId (uint256) | — |
| Functions | Inputs | Outputs |
|---|---|---|
createProfile | userId (uint256), name (string), email (string), age (uint8), country (string), isKYCApproved (bool) | — |
updateProfile | userId (uint256), name (string), email (string), age (uint8), country (string), isKYCApproved (bool) | — |
deleteProfile | userId (uint256) | — |
getProfile | userId (uint256) | Tuple: { name (string), email (string), age (uint8), country (string), isKYCApproved (bool), isDeleted (bool) } |
profiles | userId (uint256) | Tuple: { name (string), email (string), age (uint8), country (string), isKYCApproved (bool), isDeleted (bool) } |
3. Add API portal middleware to your application
Middleware acts as a bridge between your blockchain network and applications, providing essential services like data indexing, API access, and event monitoring. Before adding middleware, ensure you have an application and blockchain node in place.
How to add middleware
First ensure you're authenticated:
Create a middleware:
Manage middleware
You can upload or copy paste the ABI. Please note that if you upload the ABI, the file name will be picked as the ABI name, so make sure you edit the file name of the ABI JSON file before uploading.
In a few minutes we get a REST and GraphQL API layer
To update the ABIs of an existing smart contract portal middleware, navigate to the middleware, go to the details and click on the 'manage middleware' button on the top right. Click on the 'update ABIs' item and a dialog will open. In this dialog upload the ABI file(s) you saved on your local filesystem in the previous step.
4. How to configure REST API requests in the portal
To interact with your smart contract via the API portal, follow these steps:
Get the base URL
Navigate to the connect tab in the portal middleware to obtain the base API URL. It will look something like:
For exact endpoints, refer to the portal UI. An example endpoint might look like this:
Here, {address} should be replaced with the deployed smart contract address on
the blockchain.
You can find the deployed contract address in the
deployed_addresses.jsonfile located inside theignition/deploymentsfolder.
Sample request body
Here's an example JSON body for a smart contract function like createProfile:
Field descriptions
from: Public key of the wallet that will initiate the transaction. Typically, this is the deployer's address. For advanced scenarios, this can be a specific user's public address, depending on roles.gasLimit: Use a reasonably high value for zero-gas private networks. For others, determine a realistic value through trial and error. You can fine-tune this based on actual gas usage from previous transactions.gasPrice: Set to0for zero-gas networks, or specify an appropriate value for gas-charging private or public networks.simulate: Leave astruefor a dry run before sending actual transactions.metadata: Can be left empty or with default values unless your application requires it.input: Include all parameters required by the smart contract function you are calling.
Authentication
Use your application access token as the API key for authentication. You can generate this token from the access tokens section in your application dashboard (left sidebar menu) and will look something like sm_aat_fd0fbe61cf102b6c.
Expected response
If the request is valid, the API will return a: 200 OK along with the transaction hash in the response body. Else various error codes with respective messages will be returned.
5. How to configure GraphQL API requests in the portal
How to configure a GraphQL request in the API portal
To query smart contract data using GraphQL in the SettleMint API portal, navigate to the GraphQL tab in the portal interface. You will see a visual GraphQL explorer that allows you to construct and test your queries easily. The endpoint for GraphQL is provided under the connect tab, typically looking like:
In the explorer, start by selecting the appropriate query object exposed in the
API, such as UserSmartContractAbi. You'll need to provide the address
parameter, which corresponds to the deployed smart contract address. This
address ensures that your request is directed to the correct smart contract
instance on-chain.
Once the address is entered, you can choose the function or field you want to
query. For example, selecting the profiles field and providing a uint256 ID
(such as "101") will retrieve the user profile associated with that ID. You
can then pick which fields of the profile you want to fetch, like name,
email, age, country, isKYCApproved, and isDeleted.
After you've built your query, hit the play button to execute it. If successful, the response will appear on the right-hand panel, showing the structured result returned from the smart contract. In this case, you might get a profile with a name, email, country, age, and flags indicating whether the profile is deleted or KYC-approved.
This intuitive interface allows developers to rapidly test GraphQL queries without needing to write code or leave the portal. This can be used for debugging, exploring contract data, and integrating smart contract logic into frontend or backend systems using GraphQL.
Congratulations!
You have successfully deployed smart contract API portal and have generated APIs to write data on chain.
From here you can proceed for setting up graph middleware for indexing data and get GraphQL API layer for reading data stored on chain via smart contract interactions.