spintax-net Partner API

openapi: 3.2.0
info:
  title: clx management Partner API
  version: 0.8.0
  description: 'The /v1 API of clx (docs/spec.md §15). The clx.cx page is a thin client over the same endpoints.

    Authorization: `Bearer ` from a signed-in page, or `Bearer clx_…` — an API key

    (one on the `free` plan, up to 5 on `api`). Every POST, PUT, PATCH and DELETE takes an `Idempotency-Key` header, required

    with an API key; a repeat with the same body replays the first answer for 24 hours.

    Errors: `{ "error": { "code", "message", "details"? } }`. This file grows with each stage; a

    test checks that every route in the code is here and back.'
servers:
- url: https://clx.cx
security:
- bearer: []
tags:
- name: Partner
paths:
  /v1/partner:
    get:
      summary: The partner program — your code, links, referrals and wallet (scope billing)
      description: 'Every user is a partner (docs/spec.md §19): 30% of each credited top-up of the people you

        referred, for life, one level, held 30 days. Your links: `https://clx.cx/?ref=CODE` and the

        bot''s `start=ref_CODE`. Money is integer micro-USD; the wallet''s available sum leaves out

        commissions still held, and a refund of a referral''s top-up takes its share back

        (`clawback`), which may take the wallet below zero.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partner'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Partner
      operationId: getV1Partner
      x-operation-id-source: derived
  /v1/partner/transfer:
    post:
      summary: Move money from the partner wallet to your clx balance (page session only)
      description: 'At most what is available; needs a confirmed e-mail and an Idempotency-Key

        (`insufficient_balance` when the wallet does not have it).'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - usd
              properties:
                usd:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 100000
                  multipleOf: 0.01
                  description: dollars, at most cents
      responses:
        '200':
          description: Moved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partner'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Partner
      operationId: postV1PartnerTransfer
      x-operation-id-source: derived
  /v1/partner/payouts:
    post:
      summary: Ask for a payout in USDT TRC-20 (page session only)
      description: 'From $20, to a Tron address, at most what is available; its money is reserved at once and

        an operator sends it by hand, or refuses it and the money returns. Needs a confirmed e-mail

        and an Idempotency-Key.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - usd
              - address
              properties:
                usd:
                  type: number
                  minimum: 20
                  maximum: 100000
                  multipleOf: 0.01
                  description: dollars, at most cents
                address:
                  type: string
                  description: a USDT TRC-20 (Tron) address
      responses:
        '201':
          description: Asked
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Partner'
                - type: object
                  properties:
                    payout_id:
                      type: integer
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Partner
      operationId: postV1PartnerPayouts
      x-operation-id-source: derived
components:
  parameters:
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: 'Partner money moves only with one: a retry with the same key never moves it twice.'
      schema:
        type: string
        minLength: 1
        maxLength: 200
        pattern: ^[!-~]{1,200}$
  schemas:
    Partner:
      type: object
      properties:
        code:
          type: string
          description: your partner code
        links:
          type: object
          properties:
            site:
              type: string
              description: clx.cx with ?ref=
            bot:
              type:
              - string
              - 'null'
              description: the Telegram bot with start=ref_
        rate_bp:
          type: integer
          description: the commission, basis points (3000 = 30%)
        hold_days:
          type: integer
        payout_min_micro_usd:
          type: integer
        referrals:
          type: integer
          description: accounts made with your code
        wallet:
          type: object
          properties:
            total_micro_usd:
              type: integer
            available_micro_usd:
              type: integer
              description: may be below zero after a clawback
            held_micro_usd:
              type: integer
        journal:
          type: array
          description: the last 50 rows, newest first
          items:
            type: object
            properties:
              id:
                type: integer
              type:
                type: string
                enum:
                - commission
                - clawback
                - transfer
                - payout
                - payout_return
              amount_micro_usd:
                type: integer
              invoice_id:
                type:
                - string
                - 'null'
              available_at:
                type:
                - string
                - 'null'
                format: date-time
                description: when a commission is no longer held
              note:
                type:
                - string
                - 'null'
              at:
                type: string
                format: date-time
        payouts:
          type: array
          description: the last 10, newest first
          items:
            type: object
            properties:
              id:
                type: integer
              amount_micro_usd:
                type: integer
              address:
                type: string
              status:
                type: string
                enum:
                - requested
                - paid
                - rejected
              txid:
                type:
                - string
                - 'null'
              created_at:
                type: string
                format: date-time
              settled_at:
                type:
                - string
                - 'null'
                format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: 'Stable codes: unauthorized, invalid_request, not_found, payload_too_large,

                limit_reached, service_full, idempotency_conflict, operation_in_progress,

                scope_required, session_required, key_already_issued,

                account_taken, already_connected, account_not_ready, invalid_bootstrap,

                bootstrap_permission_error, permission_catalog, orphan_not_deleted,

                token_rights_mismatch, token_check_failed, renew_lost, rate_limited, cloudflare_unavailable,

                not_configured, internal. In an account''s or operation''s `error` (the install, §4):

                name_taken, resource_drift, cron_limit, permission_error, revoked, self_check_timeout,

                credentials_missing, credentials_unreadable (clx cannot open the stored token),

                cloudflare_error. Sites: zone_not_found, site_exists, route_conflict, site_not_active,

                update_required (external sites need a newer clx-edge),

                route_not_ours (a route clx made was changed outside clx and left in place).

                Sign-up: email_unconfirmed (POST /v1/accounts before the address is confirmed),

                invalid_password, balance_not_empty (DELETE /v1/me while money is on the balance or the partner wallet or still moving, §18).

                Billing (docs/spec.md §18): insufficient_balance (Pro needs $9 on the balance), invoice_limit (3 pending top-ups),

                payments_unavailable (crypto top-ups not set up or the processor down),

                refund_unavailable (a top-up never credited, older than 90 days or refunded

                already), refund_open (a refund of that top-up is asked for already), paused (an

                object beyond the free plan''s limits: it can be read and deleted, not changed).

                Links: link_exists (the code is taken on that link host), link_host_not_ready (links go

                on an active host only), link_host_in_use

                (DELETE /v1/link-hosts/{id} while live links are on it). In a link host''s `error`:

                dns_record_exists (the named host already has a DNS record — never taken over),

                domain_taken (another worker''s custom domain), domain_not_ours.

                '
            message:
              type: string
            details:
              type: object
  responses:
    Error:
      description: An error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer