Endpoint reference

POST /api/v1/smart-accounts/onboarding

Request body

FieldTypeDetails
ownervalue
required
addressvalue
required
manifestIdstring
required
noncevalue
required
issuedAtinteger
required		No more than 30 seconds ahead of server time.
expiresAtinteger
required		Future Unix seconds, after issuedAt and no more than 300 seconds later.
grantobject
required		Browser-selected lowercase UUID v4 and distinct browser API key. Scopes must be exactly read, plan, relay in that order; no onchain signing or spending authority.
Fields
FieldTypeDetails
idstring (uuid)
required
botAddressvalue
required
scopesarray
required

Values: [["read","plan","relay"]]

expiresAtinteger
required		After the setup authorization expires and no more than 3600 seconds after its issuedAt.
labelstring
required
manifestRevisionstring
required
initializerHashstring
required
stateHashstring
required
signaturestring
required		Current sole owner's signature over the exact returned SetupAccount document.
proofSignaturestring
required		Browser key's CenterSetupProof signature over {setupDigest: challenge.digest}, using the SetupAccount domain. This is not a CenterBotProof signature.
JSON schema
{
  "type": "object",
  "properties": {
    "owner": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Address"
        },
        {
          "not": {
            "enum": [
              "0x0000000000000000000000000000000000000000",
              "0x0000000000000000000000000000000000000001"
            ]
          }
        }
      ]
    },
    "address": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Address"
        },
        {
          "not": {
            "enum": [
              "0x0000000000000000000000000000000000000000",
              "0x0000000000000000000000000000000000000001"
            ]
          }
        }
      ]
    },
    "manifestId": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9:_-]{1,192}$"
    },
    "nonce": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Hash"
        },
        {
          "not": {
            "const": "0x0000000000000000000000000000000000000000000000000000000000000000"
          }
        }
      ]
    },
    "issuedAt": {
      "$ref": "#/components/schemas/UnixSeconds",
      "description": "No more than 30 seconds ahead of server time."
    },
    "expiresAt": {
      "$ref": "#/components/schemas/UnixSeconds",
      "description": "Future Unix seconds, after issuedAt and no more than 300 seconds later."
    },
    "grant": {
      "$ref": "#/components/schemas/SmartOnboardingGrant"
    },
    "manifestRevision": {
      "$ref": "#/components/schemas/Hash"
    },
    "initializerHash": {
      "$ref": "#/components/schemas/Hash"
    },
    "stateHash": {
      "$ref": "#/components/schemas/Hash"
    },
    "signature": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{128}(?:1[bBcC])$",
      "description": "Current sole owner's signature over the exact returned SetupAccount document."
    },
    "proofSignature": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{128}(?:1[bBcC])$",
      "description": "Browser key's CenterSetupProof signature over {setupDigest: challenge.digest}, using the SetupAccount domain. This is not a CenterBotProof signature."
    }
  },
  "required": [
    "owner",
    "address",
    "manifestId",
    "nonce",
    "issuedAt",
    "expiresAt",
    "grant",
    "manifestRevision",
    "initializerHash",
    "stateHash",
    "signature",
    "proofSignature"
  ],
  "additionalProperties": false,
  "description": "Purpose-signed body; no generic CenterRequest signature is needed. Rechecks canonical state and atomically enrolls the API identity if absent, binds the wallet and creates the exact signed grant. Authorizes no transaction, onchain session or broader API grant."
}

Response 201

FieldTypeDetails
accountobject
required
Fields
FieldTypeDetails
idstring
required		Authority chain and lowercase owner address; the authority chain is independent of a transaction's destination chain.
ownerAddressstring
required
authorityChainIdinteger
required
profileobject
required
Fields
FieldTypeDetails
displayNamestring
required
biostring
required
avatarUrione of
required
createdAtinteger
required		Unix timestamp in seconds.
updatedAtinteger
required		Unix timestamp in seconds.
bindingobject
required
Fields
FieldTypeDetails
idstring
required
ownerAccountIdstring
required		Authority chain and lowercase owner address; the authority chain is independent of a transaction's destination chain.
ownerAddressstring
required
walletobject
required
Fields
FieldTypeDetails
chainIdinteger
required
addressstring
required
manifestIdstring
required
authorizationone of
required
stateobject
required
Fields
FieldTypeDetails
chainIdinteger
required
addressstring
required
manifestIdstring
required
manifestRevisionstring
required
ownersarray
required
thresholdinteger
required
safeNoncestring
required		uint256 as a lossless decimal string
stateHashstring
required
evidenceobject
required
codeHashesarray
required
modulesone of
required
moduleConfigurationVerifiedboolean
required
executionVerifiedboolean
required

Values: [false]

ownerProfileobject
optional
grantobject
required
Fields
FieldTypeDetails
idstring (uuid)
required
accountIdstring
required		Authority chain and lowercase owner address; the authority chain is independent of a transaction's destination chain.
botAddressstring
required
scopesarray
required		Cumulative profiles in canonical order: read; read + plan; read + plan + relay. Validation never expands or reorders the signed list.
labelstring
required
createdAtinteger
required		Unix timestamp in seconds.
expiresAtinteger
required		Unix timestamp in seconds.
revokedAtone of
required
JSON schema
{
  "type": "object",
  "properties": {
    "account": {
      "$ref": "#/components/schemas/Account"
    },
    "binding": {
      "$ref": "#/components/schemas/SmartAccountBinding"
    },
    "grant": {
      "$ref": "#/components/schemas/BotGrant"
    }
  },
  "required": [
    "account",
    "binding",
    "grant"
  ],
  "additionalProperties": false
}