--- updatedAt: 2025-07-26T16:54:38.000Z agentTools: projectIndex: https://docs.metakeep.xyz/llms.txt --- # Invoke Lambda (Batch) After lambdas are created from the `/v2/app/lambda/create` API call or imported using the `/v2/app/lambda/import` API, use this API to execute a `batch` of lambda invocations(`function calls` and `payments`(aka value transfer)) in a single transaction. This API is useful if you want to execute multiple lambda invocations in a single transaction e.g. sell your NFT, swap the proceeds for USDC, and send the USDC to your friend. > 📘 Lambda batch invoke is only supported with the BUSINESS\_WALLET Here are some sample requests: ```json Multiple invocations { "invocations": [ { "call": { "lambda": "0xc5fd96683659C62b5db12F82dB330Af04d7efaEC", "function": { "name": "mint", "args": [ "123" ] }, "pay": "0.03", "description": { "text": "Mint an NFT for 0.03 MATIC" } } }, { "call": { "lambda": "0xc5fd96683659C62b5db12F82dB330Af04d7efaEC", "function": { "name": "transfer", "args": [ "123", "0x3ecb936ef8cc5757341078b6137aabec1e21d6af" ] }, "description": { "text": "Sell NFT for 0.05 MATIC" } } }, { "pay": { "to": { "ethAddress": "0x8dc572d9FefB6A8d6c76897AF11dDf1dEbCEAfd0" }, "amount": "0.05", "description": { "text": "Transfer proceeds to a friend" } } } ], "as": { "email": "dave@example.com" }, "using": "BUSINESS_WALLET", "description": { "text": "swap NFT for MATIC and send MATIC to a friend", "image": "https://valid_image_url......" } } ``` ```json Function call with a payment { "invocations": [ { "call": { "lambda": "0xc5fd96683659C62b5db12F82dB330Af04d7efaEC", "function": { "name": "mint", "args": [ "123" ] }, "pay": "0.03", "description": { "text": "Mint an NFT for 0.03 MATIC" } } } ], "using": "BUSINESS_WALLET", "description": { "text": "purchase an NFT" } } ``` ```json Payment to a user { "invocations": [ { "pay": { "to": { "ethAddress": "0x8dc572d9FefB6A8d6c76897AF11dDf1dEbCEAfd0" }, "amount": "0.05", "description": { "text": "Transfer proceeds to a friend" } } } ], "as": { "email": "rickyrohan14@gmail.com" }, "using": "BUSINESS_WALLET", "description": { "text": "transfer 0.05 MATIC to your friend", "image": "https://valid_image_url......" } } ``` Lambda batch invoke has the following properties: 1. **Atomicity**: All the invocations in the batch are executed as an atomic unit. If any invocation fails, the entire batch will fail and all the changes will be reverted. E.g. if you are selling an NFT and swapping the proceeds for USDC, the NFT will not be sold if the swap fails. 2. **Ordering**: Invocations are executed in the order they are specified in the request. E.g. if you are selling an NFT and swapping the proceeds for USDC, the NFT will be sold first and then the proceeds will be swapped for USDC. 3. **Batch size**: You can execute up to 10 invocations in a single batch. If you want to execute more than 10 invocations, please let us know. 4. **BUSINESS\_WALLET**: Lambda batch is only supported when using `BUSINESS_WALLET`. ## Invocation types Lambda batch invoke supports 2 types of invocations: 1. **Function call**: Use this invocation type to call a `lambda function`. You can specify the lambda function to call, the function name, and the function arguments. If the function is `payable`, you can also specify the `payment(aka value transfer)` to send to the function. 2. **Payment**: Use this invocation type to send a `payment(aka value transfer)` to a user or a contract. You can specify the user or contract to send the payment to and the amount to send. If you are sending a payment to a contract, make sure that the contract has a payable fallback function. ## Invoking without `as` user If you don't provide an `as` user in the request body, lambda will be invoked from your developer account and a transaction will be raised and submitted to the Queue on the blockchain. MetaKeep, behind the scenes, employs several strategies to make sure transactions succeed, and at the lowest cost. You can get the status of this blockchain transaction by querying for transaction status by copying the transactionId from this API response and querying it in [Transaction Status API](https://docs.metakeep.xyz/reference/v1apptransactionstatus). > ❗️ Replaying this API > > Once you get a `status` response as `QUEUED`, replaying this API doesn't give you the latest status; Replaying the same API with the same [`Idempotency-Key`](/reference/idempotency-key) results in the same response, always with status-`QUEUED`. You must query the [Transaction Status](https://docs.metakeep.xyz/reference/v1apptransactionstatus) API for the latest status. As you would learn from the [Transaction Status](https://docs.metakeep.xyz/reference/v1apptransactionstatus) API docs, if a transaction failed, MetaKeep would have exhausted all feasible smart AI-based strategies to recover from failure, that would have been attempted by humans and the "FAILED" status, if shown, is final. ## Invoking with `as` user If you provide an `as` user in the request body, you will get a `consentToken` back and you will have to use [Get Consent](https://docs.metakeep.xyz/reference/get-consent) flow to finish the lambda invocation. Here, the developer is agreeing to pick up the gas fee on execution so that the user doesn't have to know/understand the concept of gas. MetaKeep, behind the scenes, employs several strategies to make sure transactions succeed, and at the lowest cost. ```json Sample Response { "status": "USER_CONSENT_NEEDED", "consentToken": "CrgBAQIDAHgtrXLM7Takfd-ccn6FAthYppUrIuoEMsncIpxm4af4uUh4Cikr2YkEzasNQr9433Z-V73Hw==" } ``` ## Gas Limit This API currently has `gas limit` set to `2000000(2M)`. If you need a higher `gas limit`, please let us know. ## Gas Price The API sets the right gas price for the transaction based on AI and statistical analysis of the current network conditions for `fast and reliable transaction` confirmation. If you want even faster confirmation, you can tune the transaction speed in the [app settings](https://docs.metakeep.xyz/docs/lambda-customization). ## Error Status > 🚧 Api Error Status > > You can find error status returned by the api [here](https://docs.metakeep.xyz/reference/api-error-status#v2applambdainvokemultiple). © Copyright 2024, Passbird Research Inc. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "production", "version": "3.4" }, "servers": [ { "url": "https://api.metakeep.xyz/" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "security": [ { "sec0": [] } ], "paths": { "/v2/app/lambda/invoke/multiple": { "post": { "summary": "Invoke Lambda (Batch)", "description": "", "operationId": "v2applambdainvokemultiple", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. This allows developers to safely retry requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. [Read more](/reference/idempotency-key)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "invocations", "description", "using" ], "properties": { "invocations": { "type": "array", "description": "List of lambda functions and payments to invoke in the transaction. Specify either `call` or `pay` for each invocation.", "items": { "properties": { "call": { "type": "object", "description": "Lambda function to invoke.", "required": [ "lambda" ], "properties": { "lambda": { "type": "string", "description": "Hex encoded lambda address. This is obtained from a previous /v2/app/lambda/create or /v2/app/lambda/import API call." }, "function": { "type": "object", "description": "Lambda Function to invoke with arguments in the format `{ name: \"function_name\", args: [] }`.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Function name.", "default": "function_name" }, "args": { "type": "array", "description": "Array of function arguments. This can be left empty if the function takes no arguments. Arguments should be sent in the format described [here](https://docs.metakeep.xyz/reference/lambda-101#solidity-types-to-lambda-types).", "default": [ "123" ], "items": { "type": "string" } } } }, "pay": { "type": "string", "description": "How much `native currency`(e.g. MATIC on Polygon) to pay(aka value transfer) to the payable lambda function. This should be a decimal string with up to 18 decimals. Only supported when using `BUSINESS_WALLET`" }, "description": { "type": "object", "description": "The human readable explanation for this transaction. Useful for presenting to the user as an extra information ex: \"Swap wBTC to USDC\", and for auditing purposes.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Human understandable text explaining the transaction." } } } } }, "pay": { "type": "object", "description": "Native currency(e.g. MATIC on Polygon) payment (aka value transfer) to a user or a contract.", "required": [ "amount" ], "properties": { "to": { "type": "object", "description": "Who to make the payment.", "required": [ "ethAddress" ], "properties": { "ethAddress": { "type": "string", "description": "EVM compatible crypto wallet address of user (could be an external wallet address like Metamask / Coinbase)." } } }, "amount": { "type": "string", "description": "How much `native currency`(e.g. MATIC on Polygon) to pay(aka value transfer) to the payable lambda function. This should be a decimal string with up to 18 decimals. Only supported when using `BUSINESS_WALLET`" }, "description": { "type": "object", "description": "The human readable explanation for this payment. Useful for presenting to the user as an extra information ex: \"Swap MATIC to USDC\", and for auditing purposes.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Human understandable text explaining the transaction." } } } } } }, "type": "object" } }, "description": { "type": "object", "description": "The human understandable explanation for this transaction. Useful for presenting to the user as an extra information ex: `Swap wBTC to USDC`, and for auditing purposes. The description should include a text and an optional image.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Human understandable text explaining the transaction." }, "image": { "type": "string", "description": "An optional image URL to show along with the text." } } }, "as": { "type": "object", "description": "Invoke lambda `as` this user. If this is not set, lambda will be invoked from your developer account.", "properties": { "email": { "type": "string", "description": "Email address of the user" } } }, "using": { "type": "string", "description": "The lambda wallet type to use for the transaction. Batch invocation can only be done using `BUSINESS_WALLET`.", "default": "BUSINESS_WALLET", "enum": [ "BUSINESS_WALLET" ] } } }, "examples": { "Batch Invocation": { "value": { "invocations": [ { "call": { "lambda": "0xc5fd96683659C62b5db12F82dB330Af04d7efaEC", "function": { "name": "mint", "args": [ "123" ] }, "pay": "0.03", "description": { "text": "Mint an NFT for 0.03 MATIC" } } }, { "call": { "lambda": "0xc5fd96683659C62b5db12F82dB330Af04d7efaEC", "function": { "name": "transfer", "args": [ "123", "0x3ecb936ef8cc5757341078b6137aabec1e21d6af" ] }, "description": { "text": "Sell NFT for 0.05 MATIC" } } }, { "pay": { "to": { "ethAddress": "0x8dc572d9FefB6A8d6c76897AF11dDf1dEbCEAfd0" }, "amount": "0.05", "description": { "text": "Transfer proceeds to a friend" } } } ], "as": { "email": "rickyrohan14@gmail.com" }, "using": "BUSINESS_WALLET", "description": { "text": "swap NFT for MATIC and send MATIC to a friend", "image": "https://valid_image_url......" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Invoke as a developer": { "value": "{\n \"status\": \"QUEUED\",\n \"transactionId\": \"2d59c2f4-9766-451d-91f2-b7bcb96f51d0\",\n \"transactionHash\": \"0xb1470e0c34729974bee524b9eced35d1d553bd26e184679aa7a9e77c7571884f\",\n \"transactionChainScanUrl\": \"https://mumbai.polygonscan.com/tx/0xb1470e0c34729974bee524b9eced35d1d553bd26e184679aa7a9e77c7571884f\"\n}" }, "Invoke as a user": { "value": "{\n \"status\": \"USER_CONSENT_NEEDED\",\n \"consentToken\": \"CrgBAQIDAHgtrXLM7Takfd-ccn6FAthYppUrIuoEMsncIpxm4af4uUh4Cikr2YkEzasNQr9433Z-V73Hw==\"\n}" } }, "schema": { "oneOf": [ { "title": "Invoke as a developer", "type": "object", "properties": { "status": { "type": "string", "example": "QUEUED" }, "transactionId": { "type": "string", "example": "2d59c2f4-9766-451d-91f2-b7bcb96f51d0" }, "transactionHash": { "type": "string", "example": "0xb1470e0c34729974bee524b9eced35d1d553bd26e184679aa7a9e77c7571884f" }, "transactionChainScanUrl": { "type": "string", "example": "https://mumbai.polygonscan.com/tx/0xb1470e0c34729974bee524b9eced35d1d553bd26e184679aa7a9e77c7571884f" } } }, { "title": "Invoke as a user", "type": "object", "properties": { "status": { "type": "string", "example": "USER_CONSENT_NEEDED" }, "consentToken": { "type": "string", "example": "CrgBAQIDAHgtrXLM7Takfd-ccn6FAthYppUrIuoEMsncIpxm4af4uUh4Cikr2YkEzasNQr9433Z-V73Hw==" } } } ] } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```