Skip to main content

Endpoints List RESTful API

The Defactor Postman Collection comprises a suite of pre-configured API requests designed for seamless integration into the Postman application, facilitating access to the services offered by the Defactor API.

This API offers dual modes of interaction with the smart contract: firstly, via the RESTful API; and secondly, through the GraphQL API.

It facilitates interaction with various Pools smart contracts by providing an intuitive interface that maps the actions to straightforward concepts, such as create, lend, borrow, repaid, etc. Also, it enables seamless communication with smart contracts configured across multiple blockchain networks. It is necessary to specify the network and contract name in each request payload.

Outlined below is a detailed overview of the API's functionalities, leveraging a designated instance of the counterpartypool contract as the primary data source.

info

The counterpartypool contract is based on a token that follows the erc20 token standard that has a set precision. For example it can be usdc, euroc with a exactly a precision of 6 or any other token that meets the above mentioned requirements.

Then, 10500000 is equivalent to 10.5 USDC.


Security Details

To secure the API access control, all requests are made through Hasura which provides secure GraphQL, and RESTful endpoints restricted by a role-based authorization system.

Those endpoints that return public blockchain data do not require authentication for use. Query type requests are opened under the guest role, while mutation type needs a token with admin role.

For those that can modify data the API expects a valid authorization header containing a bearer token. These tokens are implemented as JSON Web Tokens (JWTs) issued by the server.

The security of the JWT is because it is signed by a secret key and has a configurable expiration time, which by default is 60 minutes.

Upon receiving a request, Hasura decodes and validates the JWT, which contains user account data, and their corresponding role. If the role lacks the necessary permissions or the token is invalid, expired or missing, the request is promptly rejected.

Authentication

Login

Return a JSON Web Token (JWT) access token and refresh token. By default, the access token has a maturity of 60 minutes, but it may vary depending on the server configuration.

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/login

Request Body

{
"session": {
"address": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5"
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating the generated access token and refresh token. This object encompasses the following attributes:

{
"v1Login": {
"res": {
"accessToken": "<jwt>",
"refreshToken": "0a1a6d5f-1bf9-4540-8c22-d9442a75476f"
},
"success": true
}
}

Restore Session

Return a new access and refresh token.

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/restore-session

Request Body

{
"session": {
"refreshToken": "e6781b1a-ff37-4074-8b9e-39953b5a4f9d"
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating the generated access token and refresh token. This object encompasses the following attributes:

{
"v1RestoreSession": {
"res": {
"accessToken": "<jwt>",
"refreshToken": "0a1a6d5f-1bf9-4540-8c22-d9442a75476f"
},
"success": true
}
}

Pools

Unlike the contract, the status are in lowercase; Additionally, to streamline interaction the API include intermediate status such as collectable, closable, and archivable.

To maintain a common interface between API endpoints the structure of the counterparty pool is mapped as follows:

Counterparty Pool contractAPI
totalCommittedsupplied
deadlineendTime (as Date)
createdAtstartDate (as Date)
minimumAPRinterest (as Percentage)
totalRewardsrepaid
rewardsPaidOutrewards

The collateralDetails is an array which each element has the following properties:

PropertyDescription
contractAddressThe address where the collateral token is deployed.
amountThe amount of tokens that are put as collateral.
idOptional id if collateral is an ERC721 contract.

Create Pool

Create a new pool with the indicated collateral tokens using the collateralDetails schema.

HTTP Request Method: POST

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/create-pool

Request Body

{
"pool": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"endTime": "2024-08-09T23:58:00.000",
"interest": 10,
"softCap": "300000000", // 300 USDC
"hardCap": "800000000", // 800 USDC
"collateralDetails": [{
"address": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"amount": "500000000",
}]
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1CreatePool": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Get Pool

Retrieves the data associated with the specified poolId.

HTTP Request Method: GET

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/get-pool

Request Body

{
"pool": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"poolId": "6"
}
}

Response

Upon successful request completion, the server will return a status code of 200 along with a JSON object containing pool information. This object encompasses the following attributes:

{
"v1GetPool": {
"res": {
"borrowed": "980000",
"closedTime": "2024-07-18T20:45:30.000Z",
"collateralDetails": [],
"endTime": "2024-07-18T20:44:07.000Z",
"hardCap": "5000000",
"id": "0",
"interest": 1,
"metadata": {
"collateralDetails": []
},
"poolOwner": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"repaid": "2000000",
"rewards": "2000000",
"softCap": "3000000",
"startDate": "2024-07-18T20:43:12.000Z",
"status": "closed",
"supplied": "1000000"
},
"success": true
}
}

Get Pools

Retrieves the data associated with the pools specified in the pagination parameters. If the offset exceeds the total number of pools, the API will return an empty list.

HTTP Request Method: GET

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/get-pools

Request Body

{
"pool": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"offset": "6",
"limit": "10"
}
}

Response

Upon successful request completion, the server will respond with a status code of 200, accompanied by a JSON object containing information regarding the pools. This object comprises the following attributes:

{
"v1GetPools": {
"res": {
"data":
[{
"borrowed": "980000",
"collateralDetails": [],
"endTime": "2024-07-19T20:42:26.000Z",
"hardCap": "5000000",
"id": "0",
"interest": 1,
"metadata": {
"collateralDetails": []
},
"poolOwner": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"repaid": "0",
"rewards": "0",
"softCap": "1000000",
"startDate": "2024-07-18T20:42:32.000Z",
"status": "collectable",
"supplied": "1000000"
},
.
.
.
],
"more": false
},
"success": true
}
}

Get Total Pools

Returns the count of pools created within the current instance of erc20collateraltoken.

HTTP Request Method: GET

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/get-total-pools

Request Body

{
"data": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool"
}
}

Response

Upon successful request completion, the server will respond with a status code of 200 and a JSON object containing information about the total pools. This object includes the following attributes:

{
"v1GetTotalPools": {
"res": "672",
"success": true
}
}

Update Pool Metadata

Update the pool metadata

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/update-pool-metadata

Request Body

{
"pool": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"id": "0",
"name": "FACTR Pool 0",
"description": "FACTR is a tool that facilitates the connection between the traditional world of assets and the decentralized ecosystem of cryptocurrencies. Explore more about Defactor and its potential in the financial world!",
"logo": "https://assets.coingecko.com/coins/images/19201/standard/jFLSu4U9_400x400.png?1696518648",
"collateralDetails": [
{
"address": "0x60E87395b0101F85C623c38Be010574f958496db",
"standard": "ERC20",
"logo": "https://assets.coingecko.com/coins/images/19201/standard/jFLSu4U9_400x400.png?1696518648"
}
]
}
}

Response

Upon successful request completion, the server will issue a status code of 200 alongside a JSON object. This object incorporates the following attributes:

{}

Close Pool

Close the specified poolId if possible.

HTTP Request Method: POST

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/close-pool

Request Body

{
"pool": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "0"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1ClosePool": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Archive Pool

Archive the specified poolId if possible.

HTTP Request Method: POST

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/archive-pool

Request Body

{
"pool": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "0"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1ArchivePool": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Lend

Lend

Lend to a pool the specific amount of the token on which the contract is based. This endpoint is equivalent to the action commitToPool in the contract.

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/lend

Request Body

{
"loan": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "2",
"amount": "300000000"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1Lend": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Repay

Repay a loan to a pool if it is active and it has not already been repaid. This endpoint is equivalent to the action depositRewards in the contract.

The counterpartypool contract needs the approval to spend money on behalf of the borrower, to give the approve the erc20 approve endpoint could be used. The amount to approve must be greater than pool.supplied + (pool.supplied * pool.interest / 100).

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/repay

Request Body

{
"loan": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "0",
"amount": "4000000000"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1Repay": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Claim Rewards

Allows the owner of the address, if they have not already done so, to claim the rewards the pool must be active or closed. This endpoints it equivalent to the action claim in the contract.

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/claim-rewards

Request Body

{
"loan": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "0"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1ClaimRewards": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Reclaim Loan

If possible recover the supplied amount to a pool. This endpoint is equivalent to the action uncommitFromPool in the contract.

HTTP Request Method: POST

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/reclaim-loan

Request Body

{
"loan": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "2"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1ReclaimLoan": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Borrow

Borrow

Borrow the supplied amount of the base token from the pool if the deadline was reached and status is created. This endpoint is equivalent to the action collectPool in the contract.

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/borrow

Request Body

{
"borrow": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"poolId": "1"
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1Borrow": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Utilities

Erc20 Approve

Authorize a third party address to expend a designated sum of funds of the indicated token.

PropertyDescription
amountThe amount to approve.
addressThe address where the counterpartypool contract is deployed.

HTTP Request Method: POST

Roles: Admin

Request URL: {{BASE_RESTFUL_URL}}/v1/erc20-approve

Request Body

{
"token": {
"network": "{{NETWORK_NAME}}",
"contractName": "counterparty-pool",
"data": {
"address": "0xec92Ca91907fD64E446122953601E774Fd3CD6e6",
"amount": 200000000
}
}
}

Response

Upon successful completion of a request, the server will issue a status code of 200 along with a JSON object encapsulating pertinent blockchain transaction details. This object encompasses the following attributes:

{
"v1Erc20Approve": {
"res": {
"_type": "TransactionResponse",
"accessList": [],
"blobVersionedHashes": null,
"blockHash": null,
"blockNumber": null,
"chainId": "80001",
"from": "0xa8983Fe59b2F08F9F1B3E833c5D47B256F7FE0d5",
"gasLimit": "150012",
"gasPrice": null,
"hash": "0x68dc6f65b96a427c4c289371637b063bbe20d9841d6c8183f06e657ab10efb1e",
.
.
.
},
"success": true
}
}

Get Usdc

Returns the configured usdc contract address within the erc20collateraltoken instance.

HTTP Request Method: GET

Roles: Guest

Request URL: {{BASE_RESTFUL_URL}}/v1/get-usdc

Request Body

{
"data": {
"network": "{{NETWORK_NAME}}"
}
}

Response

Upon successful request completion, the server will issue a status code of 200 alongside a JSON object containing the address information for usdc. This object incorporates the following attributes:

{
"v1GetUsdc": {
"res": "0x80D9E7bC3D962878b292F9536b38E52e266a77Fd",
"success": true
}
}

Get Config

HTTP Request Method: GET

Request URL: {{BASE_RESTFUL_URL}}/get-config

Request Body

{}

Error Reference

Error Response Format

The errors have the following schema:

PropertyDescription
errorThe description of the error
pathThe path to the field that caused the error
codeThe error code

Examples

The variable has a wrong type:

{
"error": "expected a string for type 'String', but found a number",
"path": "$.selectionSet.v1GetPool.args.pool.poolId",
"code": "validation-failed"
}

The variable is missing in the request body:

{
"error": "missing required field 'poolId'",
"path": "$.selectionSet.v1GetPool.args.pool.poolId",
"code": "validation-failed"
}

The field does not exists or the role has no permissions:

{
"error": "field 'v1UpdatePoolMetadata' not found in type: 'mutation_root'",
"path": "$.selectionSet.v1UpdatePoolMetadata",
"code": "validation-failed"
}

The variable is not in the request body schema:

{
"error": "Unexpected variable pool",
"path": "$",
"code": "bad-request"
}

The endpoint does not exists:

{
"error": "Endpoint not found",
"path": "$",
"code": "not-found"
}

There is no pool with the provided id:

{
"error": "Pool id 400 does not exist",
"path": "$",
"code": "unexpected"
}

Types of Errors

General

  • The date provided has already passed
    • Error message: Time must be in the future
  • The number provided is negative or zero
    • Error message: Amount cannot be negative or 0
  • The JWT is invalid
    • Error message: Could not verify JWT: JWT error
  • The input provided has a invalid value
    • Error message: Invalid request payload input
  • The string provided is not a integer number
    • Error message: Cannot convert X to BigInt

Addresses

  • The address provided is invalid
    • Error message: Address does not follow the ethereum address format
  • The address does not have the required admin role in the counterpartypool contract
    • Error message: Sender address is not admin
  • The collateral token address is invalid
    • Error message: Collateral token does not follow the ethereum address format

Pools

  • There is no pool with the provided id
    • Error message: Pool id X does not exist
  • The endTime date of the pool was reached
    • Error message: Pool has ended
  • The endpoint requires a closed pool
    • Error message: Pool is not closed
  • The endpoint requires a not closed pool
    • Error message: Pool is closed
  • The endpoint requires a completed pool
    • Error message: Pool is not completed
  • Occurs when an attempt is made to liquidate or obtain liquidation information for a completed pool
    • Error message: Pool cannot be liquidated

Lend

  • Occurs when an attempt is made to claim rewards of a loan that has already been claimed
    • Error message: Loan already claimed

Borrow

  • Occurs when an attempt is made to borrow an amount that overpass the pool balance
    • Error message: Amount overpass the pool available amount
  • Occurs when an attempt is made to repay a borrow that has already been repaid
    • Error message: Borrow already repaid

Pagination

  • The provided offset is negative
    • Error message: Offset cannot be negative
  • The provided limit is negative or zero
    • Error message: Limit cannot be negative or 0
  • The provided limit is equal to the maximum results per page, use a smaller value
    • Error message: Max limit allowed is X

Follow us:

Copyright © 2024 Defactor. All Rights Reserved