MetaLend Services API

openapi: 3.0.3
info:
  title: MetaLend Rebalancing AI Agent Guide Services API
  version: 0.1.0
  description: "API for managing cross-protocol cross-chain DeFi rebalancing operations exposing: <ul>\n  <li><b>Auth</b> – challenge/verify flow for JWT issuance.</li>\n  <li><b>Project settings</b> – fetch current project settings.</li>\n  <li><b>User configuration</b> – register or update token-level user-rebalancer settings and fetch current wallet configs.</li>\n  <li><b>Deposits</b> – create deposit intents, receive tracking IDs, and poll status through PROCESSING -> BRIDGING (cross-chain only) -> SUCCESS/FAILED/EMERGENCY_WITHDRAW. New deposits may return <b>503</b> with <b>DEPOSITS_PAUSED</b> during maintenance.</li>\n  <li><b>Withdrawals</b> – submit signed withdrawal requests, receive tracking IDs, and monitor status PROCESSING -> SUCCESS/FAILED.</li>\n  <li><b>Balances</b> – query wallet-level balances and withdraw details, as well as balances in bridge progress.</li>\n  <li><b>Rewards</b> – aggregated rewards and claim details per wallet.</li>\n  <li><b>Pools</b> – list supported protocols (Aave, Morpho, Euler, etc.), their pools, APY breakdowns, and TVL snapshots.</li>\n  <li><b>Transaction Costs</b> – current deposit/withdraw on-behalf transaction fees and minimum amounts by chain.</li>\n  <li><b>AI Agent Guide</b> – Markdown flow guide at <code>/SKILL.md</code> with signing formats, wizard requirements, and known integration gotchas.</li>\n</ul> All endpoints require an <b>X-API-Key</b>. <b>JWT authentication</b> is required on <b>deposit, withdrawal, and config update</b> operations.\n<b>Obtain API key by <a href=\"https://developer.metalend.tech/\" target=\"_blank\" rel=\"noopener noreferrer\">creating a new project</a>.</b>\nAll requests must include the Origin header. Use Origin: https://app.metalend.tech unless you have been assigned a different allowed origin."
  contact:
    name: MetaLend API Support
    email: support@metalend.tech
  termsOfService: https://metalend-inc.gitbook.io/litepaper/terms-of-service
  x-guidance: AI agents MUST read https://api.metalend.tech/SKILL.md before implementing any MetaLend operation. It contains critical signing formats, required headers, wizard flows for config setup, and known failure modes.
  x-default-api-key: a7f2b8c4d9e1f3a6b5c8d2e7f1a4b9c3d6e8f2a5b7c1d4e9f3a6b8c2d5e7f1a4
  x-api-key-guidance: Use x-default-api-key as X-API-Key for agent testing/integration. If you are the project owner, create or use your own project API key from https://developer.metalend.tech instead.
servers:
- url: https://api.metalend.tech
  description: Production server
security:
- ApiKeyAuth: []
  OriginHeader: []
tags:
- name: Services
paths:
  /v1/services:
    get:
      summary: Services directory
      description: Returns MetaLend API services directory with docs links and endpoint summaries.
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        scheme: exact
        network: eip155:8453
        amount: '1000'
        asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
        payTo: '0x7d6E22db7C2Ee44859061061f99E55257A5cEaC1'
        maxTimeoutSeconds: 60
        extra:
          name: USDC
          version: '2'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicesDirectoryResponse'
        '402':
          description: Payment required - x402 protocol response with payment requirements
          content:
            application/json:
              schema:
                type: object
                required:
                - x402Version
                - error
                - resource
                - accepts
                properties:
                  x402Version:
                    type: integer
                    example: 2
                  error:
                    type: string
                    example: Payment required
                  resource:
                    type: object
                    required:
                    - url
                    - description
                    - mimeType
                    properties:
                      url:
                        type: string
                        format: uri
                        example: https://api.metalend.tech/v1/services
                      description:
                        type: string
                      mimeType:
                        type: string
                        example: application/json
                  accepts:
                    type: array
                    items:
                      type: object
                      required:
                      - scheme
                      - network
                      - amount
                      - payTo
                      - maxTimeoutSeconds
                      - asset
                      - extra
                      properties:
                        scheme:
                          type: string
                          example: exact
                        network:
                          type: string
                          example: eip155:8453
                        amount:
                          type: string
                          example: '1000'
                        payTo:
                          type: string
                          example: '0x7d6E22db7C2Ee44859061061f99E55257A5cEaC1'
                        maxTimeoutSeconds:
                          type: integer
                          example: 60
                        asset:
                          type: string
                          example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                        extra:
                          type: object
                          properties:
                            name:
                              type: string
                              example: USD Coin
                            version:
                              type: string
                              example: '2'
                  extensions:
                    type: object
      tags:
      - Services
components:
  schemas:
    ServicesDirectoryResponse:
      type: object
      required:
      - description
      - docs
      - endpoints
      properties:
        description:
          type: string
        docs:
          type: object
          required:
          - openapiYaml
          - swaggerUi
          properties:
            openapiYaml:
              type: string
              format: uri
            swaggerUi:
              type: string
              format: uri
        endpoints:
          type: array
          items:
            type: object
            required:
            - path
            - description
            properties:
              path:
                type: string
              description:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key required for all endpoints.
    JwtAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'JWT issued by POST /v1/auth/verify. Pass as Authorization: Bearer <token>.


        x-agent-hint: agentcash and other agentic wallets strip the Authorization header for their own SIWX flow. Use X-MetaLend-JWT: Bearer <token> instead — the backend accepts both headers. Affected endpoints: POST /v1/deposits, POST /v1/withdrawals, PUT /v1/config.

        '
    OriginHeader:
      type: apiKey
      in: header
      name: Origin
      description: 'Required for CORS requests from browsers. Must match the allowed origins configured for the API key. Example: Origin: https://app.metalend.tech. Localhost is always allowed but must be specified.

        '
externalDocs:
  description: Litepaper
  url: https://metalend-inc.gitbook.io/litepaper