Create L1

Deploys a new L1 under the token's orgID.

Creating an L1 uses and async deployment pattern. Once a successful request is made the L1 will move to the Development state while AvaCloud performs checks on deployment details. Users can check the status of an L1 deployment using the Get L1 endpoint.

Request Overview

Parameters

Parameter	Example Value	Description
Idempotency-Key*	"f47ac10b-58cd-4372-a567-0e02b2c3d479"	A unique key generated by the API caller, that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

*required field

Body

Parameter	Example Value	Description
adminThreshold	1	The minimum number of admins required to approve actions on the blockchain
admins.alias	"Admin"	The display name of the admin
admins.evmAddress	"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"	The address of the admin
airdrops.address*	"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"	The address to receive the airdrop
airdrops.value*	"1000000000000000000000000"	The amount to be distributed to the address
companyName	"Pizza Planet"	The name of the company deploying the L1
deploymentType	"PoA"	Currently, only Proof of Authority (PoA) is supported
evmChainID*	4310309	A unique blockchain identifier. Must be a positive integer
gasConfig	"Low"	See the Fee Manager section to view all gas configurations
infraPlan.customerValidators*	"us-west2"	See the Validator column in the Infrastructure Regions table to view all regions for a network
infraPlan.debugNodes*	"us-east-1"	See the Debug Full and Debug Lite columns in the Infrastructure Regions table to view all regions for a network
infraPlan.dedicatedNodes*	"us-west-2"	See the RPC / WebSocket column in the Infrastructure Regions table to view all regions for a network
infraPlan.plan*	"testnet_starter_tier"	Use the Get Infra Plans endpoint to see available plans
infraPlan.rpcNodes*	"us-west2"	See the RPC / WebSocket column in the Infrastructure Regions table to view all regions for a network
infraPlan.validators*	"ap-northeast-1"	See the Validator column in the Infrastructure Regions table to view all regions for a network
infraPlan.wsNodes*	"us-east-1"	See the RPC / WebSocket column in the Infrastructure Regions table to view all regions for a network
metadata	{ "customProp": "value1" }	Additional key-value pairs that allow for custom information related to the L1
name*	"PizzaPlanetL1"	The name of your L1.
network*	"Fuji"	Specifies the network on which the L1 will be deployed, which is either "Fuji' (testnet) or "mainnet"
precompiles	See the Precompiles section for a list of available precompiles	Precompiled contracts to deploy on the L1 for faster execution of certain functions
setupInteroperability	false	This feature is not available at this time
simulateInfra	false	This feature is not available at this time
symbol*	"PIZZA"	The symbol for your token (e.g. AVAX, BTC). This is a short abbreviation (usually 3-5 characters) that will be used in transactions
transformedName*	"pizzal1"	A transformed version of your L1's name. This cannot be changed after deployment. Names must be no longer than 10 characters, contain only alphanumeric characters, and avoid generic terms like "Testnet," "Mainnet," etc.

*required field

The Create L1 endpoint has a rate limit of 50 requests per second. Please reach out to AvaCloud Client Services if this needs customizing for your use case.

Infrastructure Regions

Different components of your L1 can be deployed across various geographic locations, each with its own specific purposes (e.g. validator, RPC, etc.). Use the table below to see which infrastructure is supported between regions and networks (testnet vs mainnet). These regional configurations can be specified in the infraPlan section of your request.

Testnet

Region	Location	Validator	RPC / WebSocket	Debug Full	Debug Lite
us-east-1	N. Virginia, USA
us-west-2	Portland, Oregon, USA
eu-central-1	Frankfurt, Germany
ap-northeast-1	Tokyo, Japan
ap-northeast-2	Seoul, South Korea
ap-southeast-1	Singapore

Mainnet

Region	Location	Validator	RPC / WebSocket	Debug Full	Debug Lite
us-east-1	N. Virginia, USA
us-west-2	Portland, Oregon, USA
eu-central-1	Frankfurt, Germany
eu-west-1	Dublin, Ireland
ap-northeast-1	Tokyo, Japan
ap-northeast-2	Seoul, South Korea
ap-northeast-3	Osaka, Japan
ap-southeast-1	Singapore

Precompiles

Precompiled contracts can be deployed on your L1 for faster execution of certain functions. Each precompile has at least one admin as well as the option to add enabled users. Admins can manage and configure precompile contracts, while enabled users are granted restricted access.

Contract Manager

Control who can deploy smart contracts on your blockchain.

{
    "name": "ContractAllow",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    }
}

Fee Manager

Control who can modify the block size and dynamic gas pricing.

{
    "name": "GasUpdate",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    }
}

Gas Configuration

• "High": High disk usage and high throughput, low fees and high L1 operator cost (gasLimit: 20,000,000, gasTarget: 60,000,000)

• "Medium": Medium disk usage and medium throughput, medium fees and medium L1 operator cost (gasLimit: 15,000,000, gasTarget: 45,000,000)

• "Low": Low disk use and low throughput, higher fees but lower L1 operator cost (gasLimit: 12,000,000, gasTarget: 25,000,000)

Native Token Minter

Control who can mint additional tokens on your blockchain.

{
    "name": "NativeMinter",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    }
}

Transaction Manager

Control which wallet addresses can transact on your blockchain.

{
    "name": "TxAllow",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    }
}

Reward Manager

Designates the address where all fees collected on the L1 will be sent. This address can also be a smart contract. Alternatively, you can allow validators to keep the gas fees on the blocks that they produce. Reward configurations can be adjusted depending on the presence of rewardManagerInitialRewardConfig and the value of allowFeeRecipients, as shown below.

Burn all gas fees

{
    "name": "RewardManager",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    }
 }

Save gas fees for reward distribution

{
    "name": "RewardManager",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    },
    "rewardManagerInitialRewardConfig": {
        "allowFeeRecipients": false
        "rewardAddress": "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    }
 }

Allow block producers to claim fees

{
    "name": "RewardManager",
    "admins": [
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38"
    ],
    "enabled": [
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D"
    ],
    "addressAliases": {
        "0x2cE101c1b55cB9E88525F1328eA4FDC92AEECA38": "Admin 1",
        "0x5e5eA9F4C0DA5B3F2333A704529D1C8c8C5E6E2D": "Enabled User 1"
    },
    "rewardManagerInitialRewardConfig": {
        "allowFeeRecipients": true
        // "rewardAddress": "0x0000000000000000000000000000000000000000"
    }
 }

L1 States

AvaCloud L1s go through various deployment states during the creation of an L1, such as:

1. Development - This indicates the L1 payload request has been successfully made. AvaCloud is running additional checks before performing infra deployment.

2. InfraPending - Indicates that the L1 infrastructure is under deployment, but not finished yet.

3. Deployed - Indicates that L1 has been successfully deployed.

4. Error - Indicates some error has happened. For why it failed, the customer can check “deploymentError” field about the failure.

Common Error Messages

Code	Message	Causes
401	Unauthorized	The authentication token is typically either missing, expired, or invalid
429	Too Many Requests	The number of allowed requests per minute has been exceeded
409	we have processed the previous request with idempotency key <Idempotency-Key>	The idempotency key has already been used on a previous request
500	Key: 'CreateSubnetRequestBody.<Parameter>' Error:Field validation for '<Parameter>' failed on the 'required' tag	One of the required parameters is missing from the request body (e.g. name, evmChainID, etc.)
400	airdrop address can not be empty or 0x0000000000000000000000000000000000000000	The airdrop address is missing or a zero address
400	airdrop value <number> is less than or equal to 0	The airdrop value is not a positive integer
400	admins list cannot be empty for <Precompile>	The precompile is missing an admin
400	transaction precompile is enabled, but the admin address <address> is not in airdrop set	The admin address in the Transaction precompile is missing from the airdrop address list
400	transformed name must be unique	The transformed name has already been used
400	chainID must be unique	The chain ID has already been used
400	unable to get plan <infraPlan>	The plan is not recognized as one of the valid Infra Plans
400	the region <region> is not supported by network <network>	The region is not recognized as one of the valid Regions

---

Create a new L1

post

Creates a new L1

Authorizations

Header parameters

Idempotency-KeystringRequired

Idempotency key for creating L1

Body

adminThresholdintegerOptional

companyNamestringOptional

deploymentTypestring · enumOptionalPossible values:

evmChainIDintegerRequired

gasConfigstringOptional

namestringRequired

networkstringRequired

setupInteroperabilitybooleanOptional

simulateInfrabooleanOptional

symbolstringRequired

transformedNamestringRequired

Responses

201

Created

application/json

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

post

HTTPcURLJavaScriptPython

POST /v1/api/subnets HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Idempotency-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 724

{
  "adminThreshold": 1,
  "admins": [
    {
      "alias": "text",
      "evmAddress": "text"
    }
  ],
  "airdrops": [
    {
      "address": "text",
      "value": "text"
    }
  ],
  "companyName": "text",
  "deploymentType": "",
  "evmChainID": 1,
  "gasConfig": "text",
  "infraPlan": {
    "customerValidators": "text",
    "debugNodes": "text",
    "dedicatedNodes": "text",
    "plan": "text",
    "rpcNodes": "text",
    "validators": "text",
    "wsNodes": "text"
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "name": "text",
  "network": "text",
  "precompiles": [
    {
      "addressAliases": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "admins": [
        "text"
      ],
      "enabled": [
        "text"
      ],
      "name": "text",
      "rewardManagerInitialRewardConfig": {
        "allowFeeRecipients": true,
        "rewardAddress": "text"
      }
    }
  ],
  "setupInteroperability": true,
  "simulateInfra": true,
  "symbol": "text",
  "transformedName": "text"
}

{
  "adminThreshold": 1,
  "admins": [
    {
      "alias": "text",
      "evmAddress": "text"
    }
  ],
  "binaryInfo": {
    "customAvaGoTag": "text",
    "customGoVersion": "text",
    "customSubnetEVMTag": "text"
  },
  "bundleID": "text",
  "createdAt": 1,
  "deployInfo": {
    "avalancheSubnetID": "text",
    "blockchainID": "text",
    "customerValidators": [
      {
        "bLSPublicKey": "text",
        "cluster": "text",
        "ipAddress": "text",
        "nodeID": "text",
        "p2pPort": 1,
        "proofOfPossession": "text",
        "region": "text"
      }
    ],
    "dataDebugURLs": [
      {
        "activeSince": 1,
        "cluster": "text",
        "region": "text",
        "url": "text"
      }
    ],
    "dedicatedAPIs": [
      {
        "activeSince": 1,
        "cluster": "text",
        "region": "text",
        "url": "text"
      }
    ],
    "rpcURL": "text",
    "validatorManager": {
      "proxyAdminContractAddress": "text",
      "proxyContractAddress": "text",
      "validatorManagerAddress": "text"
    },
    "validators": [
      {
        "bLSPublicKey": "text",
        "cluster": "text",
        "ipAddress": "text",
        "nodeID": "text",
        "p2pPort": 1,
        "proofOfPossession": "text",
        "region": "text"
      }
    ],
    "vmID": "text",
    "websocketURL": "text"
  },
  "deploymentError": "text",
  "deploymentStatus": "Development",
  "deploymentType": "",
  "devnetExpiration": 1,
  "devnetIndexKey": "text",
  "devnetStartTime": 1,
  "evmChainID": "text",
  "foundationSigned": true,
  "genesis": {
    "airdrops": [
      {
        "address": "text",
        "value": "text"
      }
    ],
    "chainID": 1,
    "gasConfig": "text",
    "precompiles": [
      {
        "addressAliases": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "admins": [
          "text"
        ],
        "enabled": [
          "text"
        ],
        "name": "text",
        "rewardManagerInitialRewardConfig": {
          "allowFeeRecipients": true,
          "rewardAddress": "text"
        }
      }
    ],
    "symbol": "text",
    "vmType": "text"
  },
  "id": "text",
  "infraPlan": {
    "customerValidators": "text",
    "debugNodes": "text",
    "dedicatedNodes": "text",
    "plan": "text",
    "rpcNodes": "text",
    "validators": "text",
    "wsNodes": "text"
  },
  "isRegisteredInBridgeApp": "Y",
  "isRejected": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "metricsIngestionComplete": true,
  "name": "text",
  "network": "text",
  "orgID": "text",
  "planDetails": {
    "customerValidators": [
      {
        "cloudProvider": "aws",
        "count": 1,
        "region": "text"
      }
    ],
    "dedicatedNodes": [
      {
        "cloudProvider": "aws",
        "count": 1,
        "region": "text",
        "resources": {
          "cpu": "text",
          "memory": "text"
        },
        "size": "small"
      }
    ],
    "glacier": {
      "debugNodes": [
        {
          "cloudProvider": "aws",
          "count": 1,
          "region": "text",
          "resources": {
            "cpu": "text",
            "memory": "text"
          },
          "size": "small"
        }
      ],
      "enableIndexing": true
    },
    "metricsIndexing": true,
    "rpcNodes": [
      {
        "cloudProvider": "aws",
        "count": 1,
        "region": "text",
        "resources": {
          "cpu": "text",
          "memory": "text"
        },
        "size": "small"
      }
    ],
    "validators": [
      {
        "cloudProvider": "aws",
        "count": 1,
        "region": "text"
      }
    ],
    "wsNodes": [
      {
        "cloudProvider": "aws",
        "count": 1,
        "region": "text",
        "resources": {
          "cpu": "text",
          "memory": "text"
        },
        "size": "small"
      }
    ]
  },
  "publicExplorer": {
    "entryID": "text",
    "url": "text"
  },
  "runningAvaGoVersion": "text",
  "runningSubEVMVersion": "text",
  "setupInteroperability": true,
  "simulateInfra": true,
  "submittedAt": 1,
  "subscriptionID": "text",
  "teleporterConfiguration": {
    "awmRelayerID": "text",
    "awmRelayerStatus": "Pending",
    "messengerContractVersions": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "registryContractAddress": "text"
  },
  "transformedName": "text",
  "updatedAt": 1,
  "vrf": {
    "tos": 1
  }
}