MetaLend Auth API
Get challenge / verify challenge authentication
Get challenge / verify challenge authentication
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/metalend:metalend-auth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: MetaLend Rebalancing Auth API
version: 0.1.0
description: 'API for managing cross-protocol cross-chain DeFi rebalancing operations exposing:
Auth – challenge/verify flow for JWT issuance.'
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: Auth
description: Get challenge / verify challenge authentication
paths:
/v1/auth/challenge:
post:
summary: Create wallet challenge
description: 'Issues a challenge message that must be signed by the wallet owner.
**Rate limiting**: 1 request per 6 seconds per client IP. Excess requests receive HTTP `429` with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers (see `RateLimitExceeded` response).'
operationId: createAuthChallenge
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetChallengeRequest'
example:
walletAddress: '0x14848abF0125De79e0A5F3caA7F4EA9664a988e8'
siweDomain: app.metalend.tech
siweUri: https://app.metalend.tech
siweStatement: Sign in with Ethereum to MetaLend
chain: ETHEREUM
responses:
'200':
description: Challenge issued successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetChallengeResponse'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
walletAddressBlank:
$ref: '#/components/examples/WalletAddressBlank'
invalidAddressFormat:
$ref: '#/components/examples/InvalidAddressFormat'
invalidAddressCheckSum:
$ref: '#/components/examples/InvalidAddressCheckSum'
invalidSiweDetails:
$ref: '#/components/examples/InvalidSiweDetails'
chainNotSupported:
$ref: '#/components/examples/ChainNotSupported'
chainBlank:
$ref: '#/components/examples/ChainBlank'
'401':
$ref: '#/components/responses/UnauthorizedNoHeader'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalError'
x-agentcash-auth:
mode: free
/v1/auth/verify:
post:
summary: Verify wallet challenge
description: 'Verifies the signed challenge and issues a JWT for authenticated requests.
**Rate limiting**: 1 request per 12 seconds per client IP. Excess requests receive HTTP `429` with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers (see `RateLimitExceeded` response).'
operationId: verifyAuthChallenge
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyChallengeRequest'
example:
walletAddress: '0x14848abF0125De79e0A5F3caA7F4EA9664a988e8'
signature: '0x9c1efc293e476948580195863a66203816a3d437a04a92df95c1be979010031c35dbd856110eb161aa59f72cbfe49ff3a64fda3bdb094c2c321edfb13c8215161b'
chain: ETHEREUM
responses:
'200':
description: Challenge verified successfully
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyChallengeResponse'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
walletAddressBlank:
$ref: '#/components/examples/WalletAddressBlank'
invalidAddressFormat:
$ref: '#/components/examples/InvalidAddressFormat'
invalidAddressCheckSum:
$ref: '#/components/examples/InvalidAddressCheckSum'
chainNotSupported:
$ref: '#/components/examples/ChainNotSupported'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
noAuthHeader:
$ref: '#/components/examples/UnauthorizedNoHeader'
invalidSignature:
$ref: '#/components/examples/UnauthorizedInvalidSignature'
notAnEvmAddress:
$ref: '#/components/examples/NotAnEvmAddress'
authExpiredOrNotCreated:
$ref: '#/components/examples/AuthExpiredOrNotCreated'
chainBlank:
$ref: '#/components/examples/ChainBlank'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalError'
x-agentcash-auth:
mode: free
components:
schemas:
GetChallengeRequest:
type: object
required:
- walletAddress
- siweDomain
- siweUri
- siweStatement
properties:
walletAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: User's Ethereum wallet address (must be checksummed per EIP-55)
example: '0x14848abF0125De79e0A5F3caA7F4EA9664a988e8'
siweDomain:
type: string
description: The domain requesting the SIWE signature (e.g. "app.metalend.tech")
example: app.metalend.tech
siweUri:
type: string
description: The URI for the SIWE message (e.g. "https://app.metalend.tech")
example: https://app.metalend.tech
siweStatement:
type: string
description: The human-readable statement shown to the user in the SIWE signing prompt
example: Sign in with Ethereum to MetaLend
chain:
type:
- string
- 'null'
description: The blockchain network. Defaults to "ETHEREUM" if omitted.
default: ETHEREUM
enum:
- ETHEREUM
- BASE
- POLYGON
- ARBITRUM
- OPTIMISM
- AVALANCHE
- LINEA
example: ETHEREUM
VerifyChallengeResponse:
type: object
required:
- jwt
properties:
jwt:
type: string
description: Issued JWT for authenticated requests
VerifyChallengeRequest:
type: object
required:
- walletAddress
- signature
properties:
walletAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: User's Ethereum wallet address (must be checksummed per EIP-55)
example: '0x14848abF0125De79e0A5F3caA7F4EA9664a988e8'
signature:
type: string
description: Signed challenge message using personal_sign method
example: '0x9c1efc293e476948580195863a66203816a3d437a04a92df95c1be979010031c35dbd856110eb161aa59f72cbfe49ff3a64fda3bdb094c2c321edfb13c8215161b'
chain:
type:
- string
- 'null'
enum:
- ETHEREUM
- BASE
- POLYGON
- ARBITRUM
- OPTIMISM
- AVALANCHE
- LINEA
default: ETHEREUM
description: The blockchain network for signature verification. Defaults to "ETHEREUM" if omitted. Required for Smart Contract Wallets to specify the chain on which verification is performed.
example: ETHEREUM
ApiError:
type: object
required:
- code
- internalCode
- message
properties:
code:
type: string
description: Error category identifier
internalCode:
type: string
description: More specific error identifier
message:
type: string
description: Human-readable error message
requestId:
type: string
format: uuid
description: Unique request identifier for tracking
retryAfterSeconds:
type: integer
description: Seconds to wait before retrying (for rate limiting)
GetChallengeResponse:
type: object
required:
- message
properties:
message:
type: string
description: Challenge message to sign using personal_sign method
examples:
NotAnEvmAddress:
summary: Not an EVM address
value:
code: AUTHENTICATION_FAILED
internalCode: INVALID_EVM_ADDRESS
message: Invalid wallet address
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
UnauthorizedNoHeader:
summary: No authorization header
value:
code: AUTHENTICATION_FAILED
internalCode: NO_AUTH_INFO
message: No authentication information provided
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
ChainBlank:
summary: Chain blank
value:
code: ILLEGAL_ARGUMENT_ERROR
internalCode: CHAIN_BLANK
message: Chain cannot be blank
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
WalletAddressBlank:
summary: Wallet address blank
value:
code: ILLEGAL_ARGUMENT_ERROR
internalCode: BLANK_ADDRESS
message: Wallet address cannot be blank
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
UnauthorizedInvalidSignature:
summary: Invalid signature
value:
code: AUTHENTICATION_FAILED
internalCode: INVALID_SIGNATURE
message: Invalid signature for address '0x14848abf0125de79e0a5f3caa7f4ea9664a988e8'
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
ChainNotSupported:
summary: Chain not supported
value:
code: ILLEGAL_ARGUMENT_ERROR
internalCode: CHAIN_NOT_SUPPORTED
message: 'Chain ''STX'' is not supported. Supported chains: eth, base, polygon, arbitrum, optimism, avax, linea'
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
InvalidSiweDetails:
summary: Invalid SIWE details
value:
code: ILLEGAL_ARGUMENT_ERROR
internalCode: INVALID_SIWE_DETAILS
message: 'Invalid SIWE details: SIWE domain cannot be blank'
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
InvalidAddressCheckSum:
summary: Invalid address checksum
value:
code: ILLEGAL_ARGUMENT_ERROR
internalCode: INVALID_ADDRESS_CHECKSUM
message: Invalid Ethereum address checksum. Please ensure the address is properly checksummed (EIP-55)
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
AuthExpiredOrNotCreated:
summary: Authentication expired or not created
value:
code: AUTHENTICATION_FAILED
internalCode: AUTH_MESSAGE_EXPIRED_OR_NOT_CREATED
message: Authentication message has expired or was not created
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
InvalidAddressFormat:
summary: Invalid address format
value:
code: ILLEGAL_ARGUMENT_ERROR
internalCode: INVALID_ADDRESS_FORMAT
message: 'Invalid address format. Expected: 0x followed by 40 hexadecimal characters.'
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
responses:
RateLimitExceeded:
description: 'Too many requests for this endpoint. Limits are enforced per client IP for the public API routes backed by `RebalancerResource` (and related resources using the same filter).
Response headers (when throttled):
- `Retry-After`: seconds to wait before retrying (matches the rate-limit window duration for that endpoint).
- `X-RateLimit-Limit`: maximum requests allowed in the window (e.g. `1`).
- `X-RateLimit-Remaining`: remaining requests in the window (`0` when throttled).
- `X-RateLimit-Reset`: Unix timestamp (seconds) when the limit window resets.
`internalCode` in the JSON body is `THROTTLE_PER_IP` for IP-scoped limits (other values may apply for different scopes in the backend).
'
headers:
Retry-After:
description: Seconds to wait before retrying this endpoint.
schema:
type: integer
example: 3
X-RateLimit-Limit:
description: Maximum number of requests allowed in the current window for this endpoint.
schema:
type: integer
example: 1
X-RateLimit-Remaining:
description: Remaining requests in the current window.
schema:
type: integer
example: 0
X-RateLimit-Reset:
description: Unix timestamp (seconds) when the current limit window resets.
schema:
type: integer
format: int64
example: 1713264123
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
rateLimitExceededPerIp:
summary: Rate limit exceeded (per client IP)
value:
code: RATE_LIMIT_EXCEEDED
internalCode: THROTTLE_PER_IP
message: Rate limit exceeded. Maximum 1 requests per 3 seconds allowed. Please try again later.
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: 3
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Internal Error:
value:
code: INTERNAL_ERROR
internalCode: INTERNAL_ERROR
message: An unexpected error occurred while processing your request
requestId: 2c2f3dc1-d19a-49cb-b695-37d025e551b3
retryAfterSeconds: null
UnauthorizedNoHeader:
description: No authorization header provided
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
unauthorizedNoHeader:
$ref: '#/components/examples/UnauthorizedNoHeader'
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
x-provenance:
method: harvested
publisher: MetaLend
source: https://api.metalend.tech/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)