Create Request

Brief Description of the Create Request API, how to use it and what to expect

Route URL

/api/v1/request/create

Method

POST

Input Parameters

• Body Data:

Field	Type	Required	Description
amountInUsd	number	Yes	Positive amount in USD for the request
note	string	Yes	Description or purpose of the request
receiverWalletAddress	string	No	Ethereum wallet address (must start with 0x followed by 40 hex characters)
generatedId	string	No	Provided: Custom ID for the request to show the client Default: auto-generated
vendorId	string	No	ID of the vendor associated with this request.
feeData	object	No	Only used when an Organization fee is negotiated with Vudy. Contact us for more information.

{
    "amountInUsd": 100.15, // Any number
    "note": "A note to explain why this request was generated", // Mostly used for creator's notes
    "receiverWalletAddress": "0x1234567890123456789012345678901234567890" | undefined | null,
    "generatedId": "Custom ID to be given" | undefined,
    "vendorId": "a way to identifier the vendor" | undefined,
    /*
     * Fee Data is only available for Organizations with a preapproved API KEY
     * @param feeReceiver is mandatory and must be a valid EVM address
     * @param splits are an array of basis points that will be split between the feeReceiver and additional Receivers
     * @param additionalReceivers array of wallet addresses with whom the basis points will be shared with
     * @note splits and additionalReceivers array MUST be of the same length.
     * @note the relation is splits[0] will be the percentage shared with additionalReceivers[0] and so on.
     */
    "feeData":{
        "feeReceiver": "0x1234567890123456789012345678901234567890",
        "splits": [5000],
        "additionalReceivers": ["0x2234567890123456789012345678901234567890"],
        // In this example the fee for the Organization will be split 50% with the additionalReceiver
    }
}

Response

The server will respond with a JSON object containing the following fields:

• Success Response Body:

  {
    "success": true,
    "request": {
      "id": "uuid-string", // Vudy's request ID
      "generatedId": "USERNAME-YYYYMM-XXX", // Only if Undefined
      "status": "PENDING", // Current status of the request
      "amountUSD": 100.00  // Amount in USD to get from user
    }
  }

Error Handling

In case of an error, the server will respond with an HTTP status code that indicates the type of error encountered. The response may include the following fields in the JSON object:

• Error Response:

  {
    "error": "Invalid request data",
    // This section is in case zode returns with an error.
    "details": {
      /* Zod validation error details, structure depends on which fields failed validation */
      "fieldName": {
        "_errors": ["Error message"]
      }
    }
  }

Notes

• If generatedId is not provided, the system will automatically generate one in the format USERNAME-YYYY-MM-XXX where:

• USERNAME is the uppercase username of the API key owner

• YYYY-MM is the current year and month

• XXX is a sequential number for the user's requests in the current month

• All requests are created with a status of "PENDING"