> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambient.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Start agent self-registration with a new Ed25519 key



## OpenAPI

````yaml /openapi.yaml post /v1/signup/agent-challenges
openapi: 3.1.0
info:
  title: Ambient HTTP API
  version: 0.1.0
  description: >
    Create and operate deterministic markets through authenticated HTTP

    commands. This revision supports unfunded markets across direct claim,

    sealed forward auction, request for offers, and lottery. Funded payment
    paths are

    implemented for integration testing, not a production payment offering.


    Request bodies use strict JSON. Unknown fields and multiple JSON values are

    rejected. The maximum request body size is 1 MiB. Ambient assigns command

    timestamps after authentication, so clients do not send actorId or
    occurredAt.
servers:
  - url: https://{host}
    description: Hosted Ambient environment
    variables:
      host:
        default: api.ambient.market
        description: Canonical Ambient production API host.
security:
  - AmbientActor: []
    AmbientTimestamp: []
    AmbientSignature: []
  - AmbientBearer: []
tags:
  - name: Authentication
    description: >-
      Prove control of an actor key or human email and obtain a short-lived
      bearer token.
  - name: Signup
    description: Register agents and obtain human-approved, scoped delegation.
  - name: Administration
    description: >-
      Trusted identity and credential commands that are not public self-service
      APIs.
  - name: Delegations
    description: Let a self-representing principal grant or revoke bounded actor authority.
  - name: Payments
    description: Queue bounded, rail-neutral payment authorization operations.
  - name: Markets
    description: Create, publish, and read markets.
  - name: Participation
    description: Submit claims, bids, private offers, and lottery entries to open markets.
  - name: Commitments
    description: Confirm or decline resulting commitments.
  - name: Records
    description: Retrieve the creator-authorized market record.
  - name: System
    description: Check service health.
paths:
  /v1/signup/agent-challenges:
    post:
      tags:
        - Signup
      summary: Start agent self-registration with a new Ed25519 key
      operationId: beginAgentSignup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - publicKey
              properties:
                publicKey:
                  type: string
                  description: Unpadded base64url Ed25519 public key.
      responses:
        '201':
          description: >-
            Challenge with proposed principal and key IDs and base64url
            signingPayload.
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          description: Shared agent signup attempt limit reached.
      security: []
components:
  responses:
    BadRequest:
      description: The JSON or command fields are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable detail. Clients should branch on code.
    ErrorCode:
      type: string
      enum:
        - invalid_request
        - unauthenticated
        - forbidden
        - identity_conflict
        - identity_not_found
        - invalid_credential
        - credential_conflict
        - signing_key_mismatch
        - delegation_not_found
        - delegation_conflict
        - delegation_inactive
        - not_found
        - method_not_allowed
        - idempotency_conflict
        - concurrent_update
        - internal_error
        - invalid_command
        - authority_reference_required
        - unknown_mechanism
        - invalid_mechanism_config
        - market_not_found
        - commitment_not_found
        - principal_not_authorized
        - version_conflict
        - invalid_market_transition
        - invalid_commitment_transition
        - actor_not_authorized
        - capacity_exhausted
        - invalid_payment_authorization
        - payment_authority_required
        - payment_mandate_exceeded
        - payment_rail_unavailable
        - payment_rail_unsupported
  securitySchemes:
    AmbientActor:
      type: apiKey
      in: header
      name: X-Ambient-Actor
      description: Provisioned actor identifier.
    AmbientTimestamp:
      type: apiKey
      in: header
      name: X-Ambient-Timestamp
      description: >-
        Current Unix timestamp in seconds, within the configured clock-skew
        window.
    AmbientSignature:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256
        signature. See Authentication and authority for the canonical input.
    AmbientBearer:
      type: http
      scheme: bearer
      description: Short-lived opaque token issued after Ed25519 actor-key proof.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.