Relay MCP Server

Instructions

Implementation Reference

• src/tools/get-transaction-history.ts:23-52 (handler)

  Main handler function that executes the get_transaction_history tool. Calls getRequests API, transforms the response data into a simplified transaction format (requestId, status, chains, txs, currency, createdAt), and returns formatted output with a summary and JSON data including pagination cursor.

  async ({ user, limit, cursor }) => {
    const result = await getRequests(user, limit, cursor);
  
    const txs = result.requests.map((r) => ({
      requestId: r.id,
      status: r.status,
      originChain: r.data.inTxs[0]?.chainId,
      destinationChain: r.data.outTxs[0]?.chainId,
      originTx: r.data.inTxs[0]?.hash,
      destinationTx: r.data.outTxs[0]?.hash,
      currency: r.data.currency,
      createdAt: r.createdAt,
    }));
  
    const summary = `Found ${txs.length} transaction${txs.length !== 1 ? "s" : ""} for ${user.slice(0, 6)}...${user.slice(-4)}.${result.continuation ? " More results available (use cursor to paginate)." : ""}`;
  
    return {
      content: [
        { type: "text", text: summary },
        {
          type: "text",
          text: JSON.stringify(
            { transactions: txs, cursor: result.continuation || null },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/get-transaction-history.ts:10-21 (schema)

  Zod schema defining the input parameters for the get_transaction_history tool: 'user' (required wallet address), 'limit' (optional number, defaults to 10), and 'cursor' (optional pagination token).

  user: z.string().describe("Wallet address to look up."),
  limit: z
    .number()
    .optional()
    .default(10)
    .describe("Max number of transactions to return. Defaults to 10."),
  cursor: z
    .string()
    .optional()
    .describe(
      "Pagination cursor from a previous response. Omit for the first page."
    ),

• src/tools/get-transaction-history.ts:5-54 (registration)

  Registration function that registers the get_transaction_history tool with the MCP server, including the tool name, description, input schema, and handler function.

  export function register(server: McpServer) {
    server.tool(
      "get_transaction_history",
      "Get past Relay bridge and swap transactions for a wallet address. Returns transaction IDs, statuses, chains, and timestamps. Supports pagination via cursor.",
      {
        user: z.string().describe("Wallet address to look up."),
        limit: z
          .number()
          .optional()
          .default(10)
          .describe("Max number of transactions to return. Defaults to 10."),
        cursor: z
          .string()
          .optional()
          .describe(
            "Pagination cursor from a previous response. Omit for the first page."
          ),
      },
      async ({ user, limit, cursor }) => {
        const result = await getRequests(user, limit, cursor);
  
        const txs = result.requests.map((r) => ({
          requestId: r.id,
          status: r.status,
          originChain: r.data.inTxs[0]?.chainId,
          destinationChain: r.data.outTxs[0]?.chainId,
          originTx: r.data.inTxs[0]?.hash,
          destinationTx: r.data.outTxs[0]?.hash,
          currency: r.data.currency,
          createdAt: r.createdAt,
        }));
  
        const summary = `Found ${txs.length} transaction${txs.length !== 1 ? "s" : ""} for ${user.slice(0, 6)}...${user.slice(-4)}.${result.continuation ? " More results available (use cursor to paginate)." : ""}`;
  
        return {
          content: [
            { type: "text", text: summary },
            {
              type: "text",
              text: JSON.stringify(
                { transactions: txs, cursor: result.continuation || null },
                null,
                2
              ),
            },
          ],
        };
      }
    );
  }

• src/relay-api.ts:313-324 (helper)

  Helper function getRequests that performs the actual API call to fetch transaction history. Accepts user address, limit, and optional continuation token, returns RequestsResponse with requests array and pagination cursor.

  export async function getRequests(
    user: string,
    limit = 10,
    continuation?: string
  ): Promise<RequestsResponse> {
    const params: Record<string, string> = {
      user,
      limit: String(limit),
    };
    if (continuation) params.continuation = continuation;
    return relayApi<RequestsResponse>("/requests", { params });
  }

• src/relay-api.ts:285-311 (schema)

  TypeScript interfaces defining the data structures: RelayRequest (transaction data with id, status, user, inTxs, outTxs, currency, timestamps) and RequestsResponse (array of RelayRequest and optional continuation token for pagination).

  export interface RelayRequest {
    id: string;
    status: string;
    user: string;
    recipient: string;
    data: {
      inTxs: Array<{
        hash: string;
        chainId: number;
        timestamp: number;
      }>;
      outTxs: Array<{
        hash: string;
        chainId: number;
        timestamp: number;
      }>;
      currency: string;
      timeEstimate: number;
    };
    createdAt: string;
    updatedAt: string;
  }
  
  export interface RequestsResponse {
    requests: RelayRequest[];
    continuation?: string;
  }