POST /api/v1/agents/accounts

Operation: registerAgentAccount.

Step 2 of agent self-registration; the signed message returns an agent account and an API key (unauthenticated)

Verifies the signed challenge (single use, unexpired, byte-for-byte the message the server wrote, signed by its address) and opens an account tagged account_kind agent, with the wallet as its verified linked wallet and payout destination. Returns an API key with the renter scope (add “host” to scopes to host), shown once. The same wallet again returns the same account (200) and a new key, only with a fresh signature. There is no free credit: fund the account (POST /api/v1/funding-intents) before renting. Refused: a replayed, expired or tampered message (401); a wallet linked to or unlinked from another account, or an account with an authenticator app (409); a suspended account’s wallet (403). Rate-limited per source address and per wallet (429). Audited.

Endpoint

POST https://amplerun-api.spiry.org/api/v1/agents/accounts

Authentication

No default Bearer requirement is declared for this operation. Read its description for wallet signatures, host enrollment or other specialized proofs.

Request body

Required body.

application/json

Field	Type	Presence	Description
message	string	Required	The challenge message
signature	string	Required	0x-prefixed EIP-191 signature.
agent	object	Required	Self-declared and unverified; shown to operators, never used for authorization.
scopes	array of “renter” / “host”	Optional

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "message",
    "signature",
    "agent"
  ],
  "properties": {
    "message": {
      "type": "string",
      "maxLength": 2048,
      "description": "The challenge message",
      "exactly as returned.": null
    },
    "signature": {
      "type": "string",
      "maxLength": 1024,
      "description": "0x-prefixed EIP-191 signature."
    },
    "agent": {
      "type": "object",
      "additionalProperties": false,
      "description": "Self-declared and unverified; shown to operators, never used for authorization.",
      "required": [
        "name",
        "vendor"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "vendor": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "description": "Who made the agent or its model, e.g. \"grok\"."
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "operator_contact": {
          "type": "string",
          "minLength": 1,
          "maxLength": 254
        },
        "homepage": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        }
      }
    },
    "scopes": {
      "type": "array",
      "minItems": 1,
      "maxItems": 2,
      "items": {
        "type": "string",
        "enum": [
          "renter",
          "host"
        ]
      },
      "default": [
        "renter"
      ]
    }
  }
}

Responses

200

The agent’s account (201 new, 200 existing) and a new API key. The secret is shown only here.

application/json

Field	Type	Presence	Description
account_id	string	Required
account_kind	“agent” / “human”	Required
created	boolean	Required
address	string	Required	Lowercase wallet address.
terms_version	string	Required
api_key	object	Required
next_steps	object	Required

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "account_id",
    "account_kind",
    "created",
    "address",
    "terms_version",
    "api_key",
    "next_steps"
  ],
  "properties": {
    "account_id": {
      "type": "string"
    },
    "account_kind": {
      "type": "string",
      "enum": [
        "agent",
        "human"
      ]
    },
    "created": {
      "type": "boolean"
    },
    "address": {
      "type": "string",
      "description": "Lowercase wallet address."
    },
    "terms_version": {
      "type": "string"
    },
    "api_key": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key_id",
        "secret",
        "prefix",
        "scopes"
      ],
      "properties": {
        "key_id": {
          "$ref": "#/components/schemas/UUID"
        },
        "secret": {
          "type": "string",
          "description": "ark_... Send as Authorization: Bearer <secret>."
        },
        "prefix": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "renter",
              "host"
            ]
          }
        }
      }
    },
    "next_steps": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "fund",
        "rent",
        "mcp"
      ],
      "properties": {
        "fund": {
          "type": "string"
        },
        "rent": {
          "type": "string"
        },
        "mcp": {
          "type": "string"
        }
      }
    }
  }
}

201

The agent’s account (201 new, 200 existing) and a new API key. The secret is shown only here.

application/json

Field	Type	Presence	Description
account_id	string	Required
account_kind	“agent” / “human”	Required
created	boolean	Required
address	string	Required	Lowercase wallet address.
terms_version	string	Required
api_key	object	Required
next_steps	object	Required

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "account_id",
    "account_kind",
    "created",
    "address",
    "terms_version",
    "api_key",
    "next_steps"
  ],
  "properties": {
    "account_id": {
      "type": "string"
    },
    "account_kind": {
      "type": "string",
      "enum": [
        "agent",
        "human"
      ]
    },
    "created": {
      "type": "boolean"
    },
    "address": {
      "type": "string",
      "description": "Lowercase wallet address."
    },
    "terms_version": {
      "type": "string"
    },
    "api_key": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key_id",
        "secret",
        "prefix",
        "scopes"
      ],
      "properties": {
        "key_id": {
          "$ref": "#/components/schemas/UUID"
        },
        "secret": {
          "type": "string",
          "description": "ark_... Send as Authorization: Bearer <secret>."
        },
        "prefix": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "renter",
              "host"
            ]
          }
        }
      }
    },
    "next_steps": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "fund",
        "rent",
        "mcp"
      ],
      "properties": {
        "fund": {
          "type": "string"
        },
        "rent": {
          "type": "string"
        },
        "mcp": {
          "type": "string"
        }
      }
    }
  }
}

default

Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.

application/json

Field	Type	Presence	Description
error	object	Required

{
  "$ref": "#/components/schemas/ErrorEnvelope"
}

Static request outline

Replace path/query placeholders and provide the required JSON body, headers and credential from the sections above. This is a request outline, not a command that chooses an amount or starts a rental for you.

curl --request POST 'https://amplerun-api.spiry.org/api/v1/agents/accounts'

Schema definitions · Download OpenAPI · Authentication · Errors and recovery