POST /buildIntentNaturalLanguage

This endpoint processes a natural language intent and returns a text response. If a valid intent is detected, it also returns the corresponding input_positions and target_weights required to quote and execute the intent.

This API simplifies the process of converting natural language trade goals into executable intents, which can be traded using Haiku Intents. It enables developers to build seamless workflows, from understanding a user's intent to executing the final transaction.

Developers and traders can use this API to:

• Convert natural language into intent: Transform complex user instructions (e.g. "I want to lend all my stablecoins") into structured, executable intents.

• Leverage pre-formatted data: Use wallet positions and prices retrieved from the GET /tokenBalances API to provide structured input for intent creation.
• Validate through quoting: Pass the generated positions and weights to the POST /quoteIntent API to preview the trade, including fees and expected outcomes.
• Execute intents seamlessly: Finalise the transaction using the POST /solveIntent API to generate an unsigned EVM transaction ready for signing and broadcasting.

POST /buildIntentNaturalLanguage

Base URL: https://api.haiku.trade/v1

Parameter	Type	Description
intent	string	The user's natural language intent (e.g. "I want to lend all my stablecoins")
wallet_positions	object	A JSON object of wallet token positions - can be retrieved from GET /tokenBalances
prices	object	A JSON object of token prices corresponding to the wallet positions - can be retrieved from GET /tokenBalances

curl 'https://api.haiku.trade/v1/buildIntentNaturalLanguage' \
-H 'Content-Type: application/json' \
-d '{
    "wallet_positions": {
        "base:0x4158734d47fc9692176b5085e0f52ee0da5d47f1": 0.5166843500336669,
        "base:0x4200000000000000000000000000000000000006": 0.000002519875671558,
        "base:0x50c5725949a6f0c72e6c4a641f24049a917db0cb": 1.5084733275230073
    },
    "prices": {
        "base:0x4158734d47fc9692176b5085e0f52ee0da5d47f1": 1.6659677613197699,
        "base:0x4200000000000000000000000000000000000006": 2197.39,
        "base:0x50c5725949a6f0c72e6c4a641f24049a917db0cb": 1
    },
    "intent": "I want to lend a bunch of blue chip crypto on aave",
    "service": "AZURE_DEPLOYED"
}'

This endpoint returns a JSON object generated by processing the given intent.

Parameter	Type	Description
input_positions_str	object	A human-readable string representing the input positions.
target_weights_str	object	A human-readable string representing the target positions.
input_positions	object	Structured input positions for quoting the intent - for use in POST /solveIntent
target_weights	object	Structured target weights for quoting the intent - for use in POST /solveIntent
response	string	Textual explanation of the action taken by the model based on the intent

{
    "input_positions_str": {
        "token_positions": {
            "ETH(Arbitrum)": 0.001947130727406257
        },
        "collateral_positions": {},
        "debt_positions": {}
    },
    "target_weights_str": {
        "token_positions": {},
        "collateral_positions": {
            "ETH[Aave](Arbitrum)": 1
        },
        "debt_positions": {}
    },
    "input_positions": {
        "arb:0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee": 0.001947130727406257
    },
    "target_weights": {
        "arb:0xe50fa9b3c56ffb159cb0fca61f5c9d750e8128c8": 1
    },
    "response": "Since you wanted to lend some blue chip crypto on Aave, I chose to move ETH to Aave as the lending position since you had ETH in your wallet."
}

Below is the recommended flow for users processing natural language intents using Haiku's API suite.

1. Fetch wallet positions: Use the GET /tokenBalances endpoint to retrieve the user's formatted balances and prices.
2. Submit the natural language prompt: Send the user's prompt (e.g. "I want to lend my stablecoins") along with the wallet positions and prices to the POST /buildIntentNaturalLanguage endpoint.

3. Handle the model response:

   1. if a valid intent is generated (i.e. the response contains input_positions and target_weights), proceed to the next step.

   2. if no intent is generated, prompt the user for more context and re-submit the request.

4. [Optional] Fine-tune the intent: Edit the generated input_positions and target_weights if adjustments are required.

5. [Optional] Quote the intent: Send the intent to POST /v1/quoteIntent to receive a human-readable quote (tokens, fees, expected outcomes).

6. Submit for trade execution: Pass the generated input_positions and target_weights to the POST /solveIntent endpoint to generate an unsigned EVM transaction, ready for signing and broadcasting on chain.