AmpleRun Wallets API

openapi: 3.2.0
info:
  title: Amplerun Com Wallets API
  version: 3.0.0
  description: 'Operations tagged wallets across 2 of this provider''s published API definitions: openapi.json, amplerun-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://amplerun-api.spiry.org
  description: Production machine API (direct origin)
- url: https://amplerun.com
  description: Production frontend-compatible API origin
tags:
- name: Wallets
  description: SIWE wallet bindings on Base and the payout destination.
paths:
  /api/v1/wallets:
    get:
      operationId: listWallets
      tags:
      - Wallets
      summary: List wallet bindings (verified self)
      security:
      - sessionAuth: []
      responses:
        '200':
          description: Wallet bindings.
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WalletBinding'
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://amplerun-api.spiry.org
      description: Production machine API (direct origin)
    - url: https://amplerun.com
      description: Production frontend-compatible API origin
  /api/v1/wallets/nonce:
    post:
      operationId: createWalletNonce
      tags:
      - Wallets
      summary: SIWE nonce (verified self, re-auth)
      description: Five-minute single-use nonce with exact origin/URI, chain, issued/expiration time and server-session binding.
      security:
      - sessionAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Single-use nonce.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - nonce
                - expires_at
                properties:
                  nonce:
                    type: string
                  expires_at:
                    $ref: '#/components/schemas/Rfc3339Utc'
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://amplerun-api.spiry.org
      description: Production machine API (direct origin)
    - url: https://amplerun.com
      description: Production frontend-compatible API origin
  /api/v1/wallets/link:
    post:
      operationId: linkWallet
      tags:
      - Wallets
      summary: Link wallet via SIWE proof (verified self, re-auth)
      description: Binds chain/address to account; nonce consumed once. UNIQUE(chain_id,address) across accounts.
      security:
      - sessionAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - chain_id
              - address
              - siwe_message
              - signature
              properties:
                chain_id:
                  const: 8453
                address:
                  $ref: '#/components/schemas/EvmAddress'
                siwe_message:
                  type: string
                  minLength: 1
                signature:
                  type: string
                  minLength: 1
      responses:
        '201':
          description: Binding created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBinding'
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://amplerun-api.spiry.org
      description: Production machine API (direct origin)
    - url: https://amplerun.com
      description: Production frontend-compatible API origin
  /api/v1/wallets/{binding_id}:
    delete:
      operationId: unlinkWallet
      tags:
      - Wallets
      summary: Unlink wallet (verified self, re-auth)
      description: Blocks future use but retains historical attribution and pending-intent versions; old transfers cannot become claimable by another account.
      security:
      - sessionAuth: []
      parameters:
      - name: binding_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: Unlinked.
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://amplerun-api.spiry.org
      description: Production machine API (direct origin)
    - url: https://amplerun.com
      description: Production frontend-compatible API origin
components:
  schemas:
    EvmAddress:
      type: string
      pattern: ^0x[0-9a-fA-F]{40}$
      example: '0x1111111111111111111111111111111111111111'
    WalletBinding:
      type: object
      additionalProperties: false
      required:
      - binding_id
      - chain_id
      - address
      - version
      - linked_at
      - unlinked_at
      properties:
        binding_id:
          $ref: '#/components/schemas/UUID'
        chain_id:
          const: 8453
        address:
          $ref: '#/components/schemas/EvmAddress'
        version:
          $ref: '#/components/schemas/DecimalString'
        linked_at:
          $ref: '#/components/schemas/Rfc3339Utc'
        unlinked_at:
          anyOf:
          - $ref: '#/components/schemas/Rfc3339Utc'
          - type: 'null'
    UUID:
      type: string
      format: uuid
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      example: 3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40
    DecimalString:
      type: string
      pattern: ^(0|[1-9][0-9]*)$
      description: Unsigned base-10 integer as string; never a float.
      example: '1'
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
      - error
      example:
        error:
          code: QUOTE_EXPIRED
          message: quote expired
          retryable: false
          request_id: 3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          - retryable
          - request_id
          properties:
            code:
              type: string
              minLength: 1
              description: 'Stable machine-readable code (packages/contracts ERROR_CODES). Business routes use UNAUTHENTICATED (401), FORBIDDEN (403: missing scope, step-up or role), NOT_FOUND (404, also used where existence must not leak), INVALID_INPUT (422), ADMISSION_PAUSED and AUTHORIZATION_INVALID (403), IDEMPOTENCY_CONFLICT, CONFLICT, VERSION_CONFLICT, STALE_VERSION, STALE_FENCE, QUOTE_EXPIRED, INSUFFICIENT_FUNDS and STOP_IRREVERSIBLE (409), and UNAVAILABLE (503, or 429 when rate limited). The host-agent protocol adds BUDGET_VERSION_OLDER, BUDGET_FUNDING_MISMATCH, LEASE_SEQ_REPLAY, COMMAND_EXPIRED, UNSUPPORTED_PROTOCOL_VERSION and UNKNOWN_COMMAND_KIND. New codes may appear; handle an unknown code by its HTTP status.'
            message:
              type: string
              minLength: 1
              description: Human-readable; never contains secrets or stack traces.
            retryable:
              type: boolean
              description: 'True when the identical request may succeed later: back off and retry with the same Idempotency-Key.'
            request_id:
              $ref: '#/components/schemas/UUID'
    Rfc3339Utc:
      type: string
      format: date-time
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z$
      example: '2026-09-25T12:00:00Z'
  responses:
    Error:
      description: 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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: UUID scoped to authenticated principal, route and canonical request hash.
  securitySchemes:
    sessionAuth:
      type: http
      scheme: bearer
      description: 'Bearer credential. Programs and agents send a scoped API key as `Authorization: Bearer ark_...` (renter and/or host scope; created once at https://amplerun.com/account#api-keys or POST /api/v1/account/api-keys; the secret is shown only at creation). The web app uses a pinned Better Auth session. API keys never reach /api/v1/admin/*. Step-up (recent re-auth) is required where noted.'
externalDocs:
  description: Guides, SDKs, CLI and the MCP server for AI agents
  url: https://amplerun.com/docs/api
x-refined-from:
- openapi.json
- amplerun-com-openapi.json