Version: SDK V4 (latest)

Dashboard APIs

Using these APIs allow you to perform various actions without the need to access the dashboard UI manually.

Auth Token

To obtain an authToken required in the header, you can generate one in your account settings page on the biconomy dashboard.

1. Get list of Paymasters:

GET Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "DApp list fetched",
    "data": [
        {
            "name": "setQuoteAmoy",
            "chainId": 80002,
            "apiKey": "lU3R_dRgt.22c06266-1faa-4c47-8477-e8eaacd90330"
        },
        {
            "name": "setQuote",
            "chainId": 137,
            "apiKey": "rEEgKf5DS.a4e4f2c9-de7e-4a13-ac2d-6a9120714d61"
        }
    ]
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

2. Create a new Paymaster:

POST Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required

Body

Param	Type	Description	Required
name	string	Unique name of the DApp for a chain id	Required
type	string	Type of paymaster to be set up, in this case will be "HYBRID"	Required
chainId	number	Network on which the DApp exists	Required
version	string	String that represents the version of Paymaster to be used for the dApp	Required

200 OK

{
    "statusCode": 200,
    "message": "DApp registered successfully",
    "data": {
        "name": "setQuoteAmoy",
        "chainId": 80002,
        "apiKey": "vrTVKqTZI.7ea9dae1-9a06-4c17-a4fb-7728177b76d3" // apiKey is used to init biconomy instance to relay transactions for this Dapp
    }
}

400 Bad Request

Paymaster Name Already Exists

{
    "statusCode": 400,
    "message": "paymaster_name_exists"
}

400 Bad Request

Chain Id not supported

{
    "statusCode": 400,
    "message": "Chain ID not supported"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token is required in the headers"
}

To manage the smart contracts associated with your DApp, we provide a set of endpoints that allow you to perform actions such as adding, updating, deleting, and retrieving a list of smart contracts. To access these endpoints, you will need to include the "apiKey" parameter in the header of your requests along with the "authToken".

The "apiKey" can be obtained in two ways:

When creating your DApp, you will receive an "apiKey" as part of the registration process.

Alternatively, if you already have a DApp registered, you can find the "apiKey" in the list API of the DApp.

3. Whitelist a Smart Contract:

POST Request

URL: "https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/smart-contract"

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
name	string	Unique name of smart contract	Required
address	string	Address of smart contract	Required
abi	string	Stringified ABI of smart contract	Required
whitelistedMethods	array of strings	List of method names of smart contract which are to be sponsored by DApp	Optional

Responses

200 OK

{
    "statusCode": 200,
    "message": "Smart contract registered successfully"
}

400 Bad Request

Smart Contract Already Exists

{
    "statusCode": 400,
    "message": "Smart contract address already exists"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

4. Get List of Smart Contracts:

GET Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/smart-contract

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

200 OK

{
    "statusCode": 200,
    "message": "Smart contract list fetched",
    "data": [
        {
            "name": "Set Quote",
            "address": "0xe31b0bcbda693bff2529f4a1d9f7e8f6d924c6ab",
            "abi": "[ { \"inputs\": [ { \"internalType\": \"string\", \"name\": \"newQuote\", \"type\": \"string\" } ], \"name\": \"setQuote\", \"outputs\": [], \"stateMutability\": \"nonpayable\", \"type\": \"function\" }, { \"inputs\": [], \"stateMutability\": \"nonpayable\", \"type\": \"constructor\" }, { \"inputs\": [], \"name\": \"admin\", \"outputs\": [ { \"internalType\": \"address\", \"name\": \"\", \"type\": \"address\" } ], \"stateMutability\": \"view\", \"type\": \"function\" }, { \"inputs\": [], \"name\": \"getQuote\", \"outputs\": [ { \"internalType\": \"string\", \"name\": \"currentQuote\", \"type\": \"string\" }, { \"internalType\": \"address\", \"name\": \"currentOwner\", \"type\": \"address\" } ], \"stateMutability\": \"view\", \"type\": \"function\" }, { \"inputs\": [], \"name\": \"owner\", \"outputs\": [ { \"internalType\": \"address\", \"name\": \"\", \"type\": \"address\" } ], \"stateMutability\": \"view\", \"type\": \"function\" }, { \"inputs\": [], \"name\": \"quote\", \"outputs\": [ { \"internalType\": \"string\", \"name\": \"\", \"type\": \"string\" } ], \"stateMutability\": \"view\", \"type\": \"function\" } ]",
            "whitelistedMethods": [
                "setQuote"
            ],
            "methods": [
                "setQuote"
            ]
        }
    ]
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

5. Update Smart Contract Whitelisted Methods:

PATCH Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/smart-contract

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
address	string	Smart contract address	Required
whitelistedMethods	array of strings	List of method names of smart contract which are to be sponsored by DApp	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "Smart contract updated",
    "data": {
        "name": "Set Quote",
        "address": "0xe31b0bcbda693bff2529f4a1d9f7e8f6d924c6ab",
        "abi": "[ { \"inputs\": [ { \"internalType\": \"string\", \"name\": \"newQuote\", \"type\": \"string\" } ], \"name\": \"setQuote\", \"outputs\": [], \"stateMutability\": \"nonpayable\", \"type\": \"function\" }, { \"inputs\": [], \"stateMutability\": \"nonpayable\", \"type\": \"constructor\" }, { \"inputs\": [], \"name\": \"admin\", \"outputs\": [ { \"internalType\": \"address\", \"name\": \"\", \"type\": \"address\" } ], \"stateMutability\": \"view\", \"type\": \"function\" }, { \"inputs\": [], \"name\": \"getQuote\", \"outputs\": [ { \"internalType\": \"string\", \"name\": \"currentQuote\", \"type\": \"string\" }, { \"internalType\": \"address\", \"name\": \"currentOwner\", \"type\": \"address\" } ], \"stateMutability\": \"view\", \"type\": \"function\" }, { \"inputs\": [], \"name\": \"owner\", \"outputs\": [ { \"internalType\": \"address\", \"name\": \"\", \"type\": \"address\" } ], \"stateMutability\": \"view\", \"type\": \"function\" }, { \"inputs\": [], \"name\": \"quote\", \"outputs\": [ { \"internalType\": \"string\", \"name\": \"\", \"type\": \"string\" } ], \"stateMutability\": \"view\", \"type\": \"function\" } ]",
        "whitelistedMethods": [
            "setQuote"
        ],
        "methods": [
            "setQuote"
        ]
    }

}

400 Bad Request

Whitelisted methods must be an array

{
    "statusCode": 400,
    "message": "whitelistedMethods must be an array"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

404 Not Found

Usually, this occurs when incorrect apiKey is used or the address is not added

{
    "statusCode": 400,
    "message": "Smart contract not found"
}

6. Update Sponsorship Paymaster Funding Wallet:

It is a 3-step process.

1. Generate a message from biconomy servers, for the sponsorship paymaster.

GET Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/funding-message/{{paymasterId}}

Headers

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Responses

200 OK

{
    "statusCode": 200,
        "message": "Funding message sent",
        "data": {
        "fundingMessage": "Timestamp: November 27, 2023, 5:05 PM\nWelcome to Biconomy! This request will connect your gas tank to our app. It will not trigger a blockchain transaction or incur any fees."
    }
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

2. Sign the generated message using the private key of the EOA (Funding Wallet).

3. Send the request to biconomy to update the funding wallet address.

PATCH Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io//api/v2/public/sdk/paymaster

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
paymasterId	string	Sponsorship Paymaster Id	Required
type	string	Method Name. Use "paymasterFundingId" here	Required
signature	string	Signature generated using private key of EOA	Required
address	string	Address of the EOA which is to be updated as funding wallet	Required

Responses

200 OK

{
    "statusCode": 200,
        "message": "Paymaster updated successfully",
        "data": {
        "name": "testXXX",
        "chainId": 80002,
        "apiKey": "GwfDKydYq.2967f140-XXXX-4042-XXXX-76684f9XXXX",
        "paymasterId": "e998530d-XXXX-451e-XXXX-cb6fXXXXef54"
    }
}

400 Bad Request

This happens, when there is a signature mismatch, either because an older message is used to generate the signature, or EOA address mentioned in the request body, is not the address which signed the message.

{
    "statusCode": 400,
    "message": "Invalid signature"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

404 Not Found

Usually, this occurs when incorrect apiKey or authToken is used

{
    "statusCode": 404,
    "message": "User not found"
}

7. Delete Smart Contract

DELETE Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/smart-contract

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
address	string	Smart contract address	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "Smart contract deleted"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

404 Not Found

{
    "statusCode": 400,
    "message": "Smart contract not found"
}

8. Add spending limit rule to a paymaster

POST Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
name	string	Unique Policy name	Required
policyType	string	Pass "PAYMASTER_SA_LIMIT" for spending limit	Required
policyData	object	Described below	Required

Policy Data

Param	Type	Description	Required
type	string	"PAYMASTER"(Global limit) / "SMART_ACCOUNT" (Individual User Limit)	Required
cycleDuration	object	eg. `{value:3, unit: "hour"}`, `{value:2, unit: "day"}`. Currently only supported time units are "hour" and "day"	Required
threshold	number	Limit Value	Required
thresholdType	type	"COUNT" (Number of Userops) / "NATIVE_ASSET" (Gas Spend in native token, in eth)	Required
Responses

200 OK

{
    "statusCode": 200,
    "message": "Paymaster Policy created successfully",
    "data": {
            "_id": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "name": "paymaster limit",
            "policyType": "PAYMASTER_SA_LIMIT",
            "organisationId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "paymasterId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "createdBy": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "chainId": 84532,
            "active": true,
            "policyData": {
            "type": "PAYMASTER",
                "startTimeInEpoch": 1709053430301,
                "durationInMs": 10800000,
                "cycleDuration": {
                "value": 3,
                    "unit": "hour"
                },
                "threshold": 10,
                "thresholdType": "COUNT"
            }
       }     
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

9. Add a webhook rule to the paymaster

POST Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
name	string	Unique Policy name	Required
policyType	string	Pass "WEBHOOK" for webhook rule	Required
policyData	object	Described below	Required

Policy Data

Param	Type	Description	Required
url	string	Webhook URL which will be sent a POST request with the webhook data, and userOp	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "Paymaster Policy created successfully",
    "data": {
            "_id": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "name": "webhook rule",
            "policyType": "WEBHOOK",
            "organisationId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "paymasterId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "createdBy": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "chainId": 84532,
            "active": true,
            "policyData": {
                "url": "https://www.google.com"
             },
       }     
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

10. Add a "Wallet Deployment" rule to the paymaster

POST Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description	Required
name	string	Unique Policy name	Required
policyType	string	Pass "WALLET_DEPLOYMENT"	Required
policyData	object	Pass empty object (`{}`)	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "Paymaster Policy created successfully",
    "data": {
            "_id": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "name": "wallet deployment rule",
            "policyType": "WALLET_DEPLOYMENT",
            "organisationId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "paymasterId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "createdBy": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
            "chainId": 84532,
            "active": true,
            "policyData": {
                "operator": "walletDeployment"
             },
       }     
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

11. Get all rules for a paymaster (spending limit, webhook, wallet deployment, whitelisted contracts)

GET Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Responses

200 OK

{
  "statusCode": 200,
  "message": "Paymaster Policies found!",
  "data": [
    {
      "_id": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "name": "paymaster spending limit",
      "policyType": "PAYMASTER_SA_LIMIT",
      "organisationId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "paymasterId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "createdBy": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "chainId": 84532,
      "active": true,
      "policyData": {
        "type": "PAYMASTER",
        "startTimeInEpoch": 1709053430301,
        "durationInMs": 10800000,
        "cycleDuration": {
          "value": 3,
          "unit": "hour"
        },
        "threshold": 10,
        "thresholdType": "COUNT"
      }
    },
    {
      "_id": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "name": "wallet deployment rule",
      "policyType": "WALLET_DEPLOYMENT",
      "organisationId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "paymasterId": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "createdBy": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
      "chainId": 84532,
      "active": true,
      "policyData": {
        "operator": "walletDeployment"
      }
    }
  ]
}

401 Unauthorized

{
    "statusCode": 401,
        "message": "Auth token and API key is required in the headers"
}

12. Update spending limit rule for a paymaster

PATCH Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy/limit/:policyId

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Body

Param	Type	Description
name	string	New Policy name
cycleDuration	string	updated cycle duration
threshold	number	New spending limit threshold
thresholdType	string	New spending limit type

Responses

200 OK

{
    "statusCode": 200,
    "message": "Paymaster Limit updated"
}

On a successful update, the cycle of the spending limit will be reset and the new limit will be applied from the time of the update.

{
    "statusCode": 200,
    "message": "Paymaster Limit updated"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

12. Pause a paymaster rule

PATCH Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy/deactivate/:policyId

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "Paymaster Policy Deactivated!"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

13. Unpause a paymaster rule

PATCH Request

URL: https://paymaster-dashboard-backend.prod.biconomy.io/api/v2/public/sdk/paymaster-policy/activate/:policyId

Parameters

Header

Param	Type	Description	Required
authToken	string	Token unique to every user account	Required
apiKey	string	API Key Associated with dApp	Required

Responses

200 OK

{
    "statusCode": 200,
    "message": "Paymaster Policy Activated!"
}

401 Unauthorized

{
    "statusCode": 401,
    "message": "Auth token and API key is required in the headers"
}

Dashboard APIs

Auth Token​

1. Get list of Paymasters:​

2. Create a new Paymaster:​

3. Whitelist a Smart Contract:​

4. Get List of Smart Contracts:​

5. Update Smart Contract Whitelisted Methods:​

6. Update Sponsorship Paymaster Funding Wallet:​

It is a 3-step process.​

1. Generate a message from biconomy servers, for the sponsorship paymaster.​

2. Sign the generated message using the private key of the EOA (Funding Wallet).​

3. Send the request to biconomy to update the funding wallet address.​

7. Delete Smart Contract​

8. Add spending limit rule to a paymaster​

9. Add a webhook rule to the paymaster​

10. Add a "Wallet Deployment" rule to the paymaster​

11. Get all rules for a paymaster (spending limit, webhook, wallet deployment, whitelisted contracts)​

12. Update spending limit rule for a paymaster​

12. Pause a paymaster rule​

13. Unpause a paymaster rule​

Auth Token

1. Get list of Paymasters:

2. Create a new Paymaster:

3. Whitelist a Smart Contract:

4. Get List of Smart Contracts:

5. Update Smart Contract Whitelisted Methods:

6. Update Sponsorship Paymaster Funding Wallet:

It is a 3-step process.

1. Generate a message from biconomy servers, for the sponsorship paymaster.

2. Sign the generated message using the private key of the EOA (Funding Wallet).

3. Send the request to biconomy to update the funding wallet address.

7. Delete Smart Contract

8. Add spending limit rule to a paymaster

9. Add a webhook rule to the paymaster

10. Add a "Wallet Deployment" rule to the paymaster

11. Get all rules for a paymaster (spending limit, webhook, wallet deployment, whitelisted contracts)

12. Update spending limit rule for a paymaster

12. Pause a paymaster rule

13. Unpause a paymaster rule