GET Requests

A versatile route to fetch requests. Can fetch ALL , a single ID or MULTIPLE ids disclosed in the search params.

Route URL

/api/v1/requests/<[id] | 'all' | 'multiple'>

• [id]: Specify a request ID to check - no brackets.

• all: Retrieve all valid requests

• multiple: Retrieve a batch of ids.

Method

GET

ALL URL Search Params

The URL params are all optional. In case you only want to fetch a specific ID, then no params are needed.

Parameter	Type	Description
vendorId	string	Search for requests with a specific identifier provided by the creator of the API. This expects a string and depends directly on the API user.
token	string	Search for requests that have a specific token address. Token address structure 0x${string}
chain	string	Search for specific requests that happen on a specific chain. Refer to Chain Names
limit	number	Sets a limit of requests to fetch; default is 10, with a maximum of 100.
dateEnd	Date String	Defines an end date to check for requests made on or before that specific timestamp.
dateStart	Date String	Defines a start date to check for requests made on or after that specific timestamp.
cursor	string	id to keep track for the next paginated page to fetch.

Example Query:

/api/v1/request/all?dateStart=2025-01-01&dateEnd=2025-01-31&chain=optimism&limit=20

In this example, we want to fetch all requests from January 1s to January 31st of 2021 on the optimism chain and only show the first 20.

Pagination Request

/api/v1/request/all?limit=20&cursor=cmslekfjo1oj1p2oeijf23fs

MULTIPLE URL Search Params

When you want to fetch multiple specific IDs an ids query MUST exist in the URL queries!

Parameter	Type	Description	Example
ids	Array of IDs	all IDs comma separated and surrounded by brackets	[cmk...1234,...,cmk...1235]

Response

Upon a successful GET request, the server will respond with a JSON object containing the following fields:

• Response Body:

  {
      "success": true,
      "data": Array<{
          status: "COMPLETED" | "FAILED"| "PENDING" | "PROCESSING" | "CANCELLED";
          id: string;
          generatedId: string;
          vendorId: string;
          amountUSD: number;
          chain: string | null;
          txHash: string | null;
          note: string | null;
          createdAt: Date;
          updatedAt: Date;
      }>,
      "pagination": {
          // Pagination only populates on the ALL api
          total: number;
          limit: number;
          nextCursor: string;
      }
  }

Property	Description
success	Indicator of a successful call.
data[#].status	The status of the request
data[#].id	The ID of the request on Vudy's Database
data[#].generatedId	The string ID generated either by Vudy or client when request was created.
data[#].amountUSD	The USD amount of the request
data[#].chain	The Chain where the request was fulfilled
data[#].txHash	The Transaction hash that records the request fulfillment
data[#].note	Notes added by the user
data[#].createdAt	Timestamp when request was created
data[#]. updatedAt	Timestamp when request was last updated.
pagination.total	Total amount of the requests created by the user
pagination.limit	The number of request per call
pagination.nextCursor	The id of the cursor position to use when using pagination.

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 Responses and specific messages with plausible causes:

{
    "error": <ERROR MESSAGE GOES HERE>
}

• 400: Bad Request

  • IDs must be provided as query parameters

    • ids parameter was not found

    • ids parameter are not correctly formatted, interim ids

  • Invalid IDs format. Expected format: ids=[id1,id2,id3]

    • ids were not properly formatted, check brackets

• 401: Unauthorized

  • API key is required

    • API is not found or invalid

  • Invalid API key

    • API key is invalid

• 404: Not Found

  • No requests found

    • Multiple ids requests, none of the request ids were found.

  • Request not found

    • Single id looked for but not found.